Home | About | Sematext search-lucene.com search-hadoop.com
 Search Hadoop and all its subprojects:

Switch to Threaded View
Accumulo >> mail # dev >> Thoughts on useless/malformed javadoc comments


Copy link to this message
-
Re: Thoughts on useless/malformed javadoc comments
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
> >
>