accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher <>
Subject Thoughts on useless/malformed javadoc comments
Date Thu, 31 Jan 2013 00:56:30 GMT
(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

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message