-Re: Thoughts on useless/malformed javadoc comments
Christopher 2013-02-03, 22:08
I created ACCUMULO-1031 for this.
Christopher L Tubbs II
On Wed, Jan 30, 2013 at 8:20 PM, Eric Newton <[EMAIL PROTECTED]> wrote:
> I avoid method-level documentation unless something surprising is going on.
> On Wed, Jan 30, 2013 at 7:56 PM, Christopher <[EMAIL PROTECTED]> wrote:
> > (For the record, when I say "useless", I mean javadoc comments that
> > solely of the auto-generated skeleton, derived from the method signature,
> > with little or nothing added)
> > In our code template, we add javadoc tags to new methods, classes, etc. I
> > think this is a good idea... except that this also tends to generate a
> > of "malformed javadoc" warnings if you check for those in your
> > (I do, because I dislike javadocs that break and/or become useless).
> > I'm wondering if it's better to remove this from the code template, so
> > javadocs that get automatically generated, but then immediately
> > and subsequently ignored (worse when the javadoc references a param from
> > previous version of the method that no longer exists or was renamed),
> > keep appearing throughout the code.
> > The risks associated with removing these from the code template is that
> > javadocs won't be added to the public API, unless we prioritize the act
> > consciously and thoughtfully adding them.
> > The risks of not removing it is that we have a bunch of useless and/or
> > malformed javadocs, or even just out-of-date javadocs that no longer
> > reflect the method signature or functionality, that stick around just
> > because it's part of the code template, but not because we consciously
> > wanted one, and remain that way because it isn't a priority to fix them.
> > Perhaps this is just a personal pet peeve that I should get over, but I
> > feel like this isn't the best option.
> > Of course, we could internally discourage the use of javadoc comments
> > don't serve a function or are malformed, and encourage deliberately
> > them up-to-date in the public API.
> > Anybody have any thoughts on this?
> > --
> > Christopher L Tubbs II
> > http://gravatar.com/ctubbsii