I created ACCUMULO-1031 for this.
-- Christopher L Tubbs II http://gravatar.com/ctubbsii On Wed, Jan 30, 2013 at 8:20 PM, Eric Newton <[email protected]> wrote: > +1 > > 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 > > http://gravatar.com/ctubbsii > > >
