systemml-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Frederick R Reiss" <frre...@us.ibm.com>
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?

Fred



From:	Luciano Resende <luckbr1975@gmail.com>
To:	dev@systemml.incubator.apache.org
Date:	09/30/2016 03:18 PM
Subject:	Re: Enhancing SystemML JavaDocs



On Fri, Sep 30, 2016 at 1:42 PM, Deron Eriksson <deroneriksson@gmail.com>
wrote:

> 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
ec,
> boolean recursive)
> throws DMLRuntimeException
>
> Here, someone has automatically generated a javadoc comment. The
developer
> has failed to correct the missing 'recursive' parameter. If a developer
has
> not created a blank javadoc comment in the first place, then the
recursive
> parameter mistake never would have been made because there never would
have
> 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
http://twitter.com/lresende1975
http://lresende.blogspot.com/



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