the wonder of javadoc

John Mazzitelli mazz at redhat.com
Wed Dec 1 04:46:13 UTC 2010


Just wanted to give a shout out to Joseph M and to document a really 
good example why javadoc is so important - even as little as a single 
line comment can make a difference.

So, I'm trying to fix the Problem Groups view. There is a comment in the 
view code that someone wrote saying "there is no underlying support for 
this criteria." - hence why its broke. Damn! I say. Now I have to go 
hunt around to find out what is missing in our criteria implementation 
that this TODO mentions, write all new code (I need a criteria that 
selects all groups, but only if the group has 1 or more members in the 
DOWN state - how exactly DO I get a filter criteria to select where 
there is "more than N" I ask??), and spend time testing. I'm thinking 
easily a couple hours this is gonna waste.

Before I went down that rabbit hole, I stopped and said, "let me make 
SURE this really isn't supported before I go wasting time and write new 
code - who knows, maybe since the time that comment was written, the 
underlying support magically appeared :) Hope springs eternal, I say.

I find this addFilterDownMemberCount in the criteria - but, I discount 
it because, well, that can't be it because I want to specify "greater 
than 1" - all of our filters that I'm used to using must match exactly 
to the filter value - so setting that filter to 1 wouldn't make sense - 
I don't want all groups with a down member count of just 1, I want 
groups with ONE OR MORE downed members.

Then I look at the javadoc - which is just a very simple one-liner:

http://git.fedorahosted.org/git/?p=rhq/rhq.git;a=blob;f=modules/core/domain/src/main/java/org/rhq/core/domain/criteria/ResourceGroupCriteria.java;h=5bd527d3479284b3d41cf268bfee798b26841c57;hb=a0f2d7877d9c606d33b07cfb52ac08dc361badae

/**
   * Only returns groups with at least this many downed implicit 
resource members
   */

Bingo!  ..."returns groups with at least this many downed members"... 
That IS what I need! This IS supported in the underlying implementation! 
It magically appeared afterall.  And there was much rejoicing. <minstrel 
music plays in background>

That javadoc - that one simple, single-line, 
probably-took-joe-10-seconds-to-write comment - just saved me hours of time.

:) I'm gonna be a little more vigilant in writing javadoc - I admit that 
I myself have been slacking in that regard lately.


More information about the rhq-devel mailing list