-Re: Thoughts on useless/malformed javadoc comments
Eric Newton 2013-01-31, 01:20
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 consist
> 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 lot
> of "malformed javadoc" warnings if you check for those in your environment
> (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 a
> previous version of the method that no longer exists or was renamed), don't
> 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 of
> 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 that
> don't serve a function or are malformed, and encourage deliberately keeping
> them up-to-date in the public API.
> Anybody have any thoughts on this?
> Christopher L Tubbs II