Home | About | Sematext search-lucene.com search-hadoop.com
 Search Hadoop and all its subprojects:

Switch to Plain View
Accumulo >> mail # dev >> Thoughts on useless/malformed javadoc comments


+
Christopher 2013-01-31, 00:56
Copy link to this message
-
Re: Thoughts on useless/malformed javadoc comments
One of the things I notice while doing a large amount of refactoring was
the pain of having to be careful about updating javadoc comments. Is it
possible to enforce comments corresponding to actual method calls? It's not
perfect but our would help.

Sent from my phone, please pardon the typos and brevity.
On Jan 30, 2013 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
> http://gravatar.com/ctubbsii
>
+
Christopher 2013-01-31, 01:17
+
Eric Newton 2013-01-31, 01:20
+
Christopher 2013-02-03, 22:08