About 2 weeks ago I had discussion with a few colleagues of mine. I have asked them what they think about following Javadoc and how to enhance it.

class Person
{
    // definition of attributes, I am not stating them to 
    // avoid attracting your attention now
 
    /**
     * Gets value of the first name property.
     * @return first name of person
     */
    public String getFirstName()
    {
        return m_FirstName;
    }
}

I have provided additional constraints:

• the class is as-is, we do not care about e.g. persistence (to avoid temptation to define maximum size).
• we do not care about constructor (or setter) and what constraints it brings.
• only this getter for Java Bean interests us here as my idea is to represent any simple method in general.
• do not speculate what else could be done in this method, just provide useful Javadoc.
• I have selected Person and first name as widely understood concept to make it harder to provide useful Javadoc (in order to shed more light into this apparently confusing concept ;-) )

As I expected I did not receive any useful (and in my opinion valid) suggestion. Following was suggested for example:

• "Maybe format could be described" (there is none in my example).
• "In case of future enhancements (e.g. encryption) it is better to have Javadoc present since beginning, because some developers will not add one when they are modifying it" (I have simplified this suggestion to make it shorter. Well, I am not sure if a group of developers who would not modify existing Javadoc is not bigger...)

I have got also useful suggestion: "I think that javadocs should not add anything unnecessary (over restrictive or superfluous or presumptuous)." Exactly that's my idea! What could Javadoc add in this case that is not already described what we have learned about in kindergarten? Yet, I have to provide one otherwise our Checkstyle will protest.

As is written in book Clean Code:

Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration.

I am not as strict about this (I am probably not able to express all my ideas cleanly often), but in general I agree that strict asking for Javadoc is healing symptoms instead of real root cause in typical code. Are you not persuaded yet? Well, what do you think about following example describing common usage of Logger?

/** Logger */
private static final Logger LOG = Logger.getLogger(Person.class);

While it is probable that there is only one Person.getFirstName() in codebase and it deserves some kind of documentation, what should I think about comment describing well known way how logger is used in about 2000 classes I have seen in our project till now?

Conclusion

I wanted to make title of this post attractive... I generally consider Javadoc to be useful. But I wanted to point out that sometimes there are valid reasons to skip it. Unfortunately Checkstyle is not able to identify these situations while people are.

A few people asked me when I am going to publish more posts here.

Eventually I will, but my urge to explain things and express my opinions is currently satisfied with my voluntary actions in my work. I had to write several articles where I try my best to express myself to sell my ideas so there is not much left to say at this blog. And it looks like it will be same for some time. It also fulfills my resolution to get better in writing (one reason I started this blog).

The only disadvantage of my current way is that I have lost about 1 hour of writing yesterday as I used Back button in browser and our wiki did not help me to locate overwritten stuff. That would not happen on my blog as I could take lost text from log. But it helped me to make it better today :-)

On the other hand, I have real feedback there and it is good feeling to see people accepting my ideas and acknowledge my effort.

BTW, my writing efforts at work are about unit testing, but I cannot publish any part here due to ownership of stuff produced by me at work...

My Dilbert 2.0 book has just arrived :-) Finally I can learn all missing tricks about OOP.

Oh, did you know that all I know about OOP I have learned from Dilbert? If not, you have probably missed this old, but very good article. It was pointed out to me by my experienced former colleague and it really made the difference back then.

Now it's pity that Dilbert 2.0 is meant as Xmas present to me from my wonderful fiancée, so I need to wait...