systemml-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Frederick R Reiss" <>
Subject Re: Enhancing SystemML JavaDocs
Date Fri, 30 Sep 2016 22:26:21 GMT

Wow, I was not aware that those empty JavaDocs were put in -- and left in
-- on purpose! To me they are the epitome of useless comments. At best they
convey exactly the same information as the line of code immediately below
them. Much of the time they end up conveying an incorrect, out-of-date
version of the same. And all of the time they limit the amount of useful
code that can be on screen at once. Are there many people on the project
who actually like the current JavaDoc policy?


From:	Luciano Resende <>
Date:	09/30/2016 03:18 PM
Subject:	Re: Enhancing SystemML JavaDocs

On Fri, Sep 30, 2016 at 1:42 PM, Deron Eriksson <>

> I do not see how these automatically generated javadocs are useful. For
> instance:
> /**
> *
> * @param pb
> * @param ec
> * @return
> * @throws DMLRuntimeException
> */
> public static double getTimeEstimate(ProgramBlock pb, ExecutionContext
> boolean recursive)
> throws DMLRuntimeException
> Here, someone has automatically generated a javadoc comment. The
> has failed to correct the missing 'recursive' parameter. If a developer
> not created a blank javadoc comment in the first place, then the
> parameter mistake never would have been made because there never would
> been a blank javadoc comment to update in the first place.
> If automatically generated javadoc comments are decided to be part of our
> coding standard, then they should be applied to all methods, not just
> random methods.
> Deron

Completely agree Deron, these are becoming stale and obsolete with the APIs
being enhanced and the javadocs being left behind. In the past I actually
tried to fix some, but as you mentioned there is a lot and we need a
community effort here.

Another approach is to make javadocs update MANDATORY for PR acceptance,
meaning that, if you touch a given file, you fix any javadoc related to
that file.

Thoughts ?

Luciano Resende

  • Unnamed multipart/related (inline, None, 0 bytes)
View raw message