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/
|