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


Copy link to this message
-
Thoughts on useless/malformed javadoc comments
(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
+
John Vines 2013-01-31, 01:10
+
Christopher 2013-01-31, 01:17
+
Eric Newton 2013-01-31, 01:20
+
Christopher 2013-02-03, 22:08