accumulo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Eric Newton <eric.new...@gmail.com>
Subject Re: Thoughts on useless/malformed javadoc comments
Date Thu, 31 Jan 2013 01:20:10 GMT
+1

I avoid method-level documentation unless something surprising is going on.



On Wed, Jan 30, 2013 at 7:56 PM, Christopher <ctubbsii@apache.org> 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
>

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