It has been already some time since I started to oppose to idea of the Best Practice. Somehow it felt like an excuse to avoid thinking and using out-of-box solution. But I could not express my concerns well enough for the Best Practice Seekers and Followers to even start doubting it.

Now, I can use very good article Death to Best Practices written by Ted Neward. I encourage everybody to read it as well as an article linked there, but I offer my favourite part:

The point is, best practices just don’t exist. They are an attempt to take a solution to a problem out of the context and apply them across the entire spectrum, and that essentially invalidates the entire thing. A solution is only useful when considered in context.

Don’t believe me? Consider this challenge: when is it not a best practice to breathe? When you’re under water, of course.

(Unless you’re a fish. Or a frog. Or maybe a prince turned into a frog.)

Point is… context matters, folks.

I am looking forward for comments saying you actually can breathe under water, you just need to... But that would be only cognitive dissonance at work.

There is a value in the best practices, I have never doubted it, but I always suggested to use name good practices to show they are not universal truth. IMHO their value is in learning how experts solve particular problem in particular context, allowing to think whether it is a good match in our context, discussing differences in contexts and to think whether we could change our assumptions about problem we are trying to solve.

I have touched this topic before in Giving gifts versus conceiving rules and also in Is Javadoc useful?

I've just finished reading blog by Uncle Bob We must ship now and deal with consequences and I like following a lot:

If you are truly concerned about getting to market early, it is almost always better to do it with fewer features, than with suboptimal design.

Whole blog is very good, but you should read Martin Fowler's blog first, to understand the context.

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.

I am big fan of Pixar. Recently I've read article written by its president Ed Catmull.

Harvard Business Review article

I like whole article, but there were a few sentences that I consider really interesting:

If you give a good idea to a mediocre team, they will screw it up; if you give a mediocre idea to a great team, they will either fix it or throw it away and come up with something that works.

it's OK to hire people who are smarter than you are

There were more, but I wanted to avoid quoting the same ideas that were quoted in blog post where I found the article.