+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 >
