Home | About | Sematext search-lucene.com search-hadoop.com
NEW: Monitor These Apps!
elasticsearch, apache solr, apache hbase, hadoop, redis, casssandra, amazon cloudwatch, mysql, memcached, apache kafka, apache zookeeper, apache storm, ubuntu, centOS, red hat, debian, puppet labs, java, senseiDB
 Search Hadoop and all its subprojects:

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


+
Christopher 2013-01-31, 00:56
+
John Vines 2013-01-31, 01:10
+
Christopher 2013-01-31, 01:17
+
Eric Newton 2013-01-31, 01:20
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
> >
>
NEW: Monitor These Apps!
elasticsearch, apache solr, apache hbase, hadoop, redis, casssandra, amazon cloudwatch, mysql, memcached, apache kafka, apache zookeeper, apache storm, ubuntu, centOS, red hat, debian, puppet labs, java, senseiDB