Back

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.

Back