Why JavaDocs suck

It’s just a funny coincident that Martin Fowler lately blogged about the “code as documentation” approach when Marcus and I were discussing our javadoc and documentation policies.

Over the years I came to the conclusion that javadocs just suck! …not as a concept – but what most teams make out of it. Especially if they are enforced via a strict checkstyle policy. Have a look at the following code and javadoc snippet:


    /**
     * Comment for m_manager
     */
    private ServiceManager m_manager;

    /** HttpRequest */
    private HttpRequest request;

    /**
     *
     * @param manager sm
     * @throws ServiceException on error
     */
    public void service(final ServiceManager manager) throws ServiceException {
        m_manager = manager;
    }

The main problem of documentation is that it needs to kept up to date. So having it separate from the code is really hard to mantain. So javadocs make this a bit easier. Especially if your favorite IDE knows how to handle them. But looking at the above code …what’s the benefit of having those comments? It is just redundant! Usually we programmers -as a species- hate redundency …but why do we write such docs then? Well, we are lazy asses and we don’t want checkstyle to barf at us. …and the IDE will just generate it for us with a keystroke.

But taking a step a back and looking at this …useless comments just clutter the code and do NOT help understanding what’s going on. So what I found useful is to focus on the general concept of the class. Explain the algorithms and usecases on the class level. At the end of the day it’s going to be a developer that will look at the code. So understanding the general idea will help him much more and he we will quickly work out the details. Maybe it’s not what you’ve learned at university – but am I the only one that sometimes removes comments to get more condensed code and visually see what’s going on there?

So my few rules are….

Explain as much as possible at the class level
If you want to force proper javadocs with checkstyle do it only for non-private or even public scoped elements
Focus on self-explanationary names. Often that’s enough or even better than comments because the explanation is visible not only at declaration time but with every use.

23. March 2005 | agile, java

francisoud

I feel the same as you about javadoc especially with getter and setter on POJO :D

In the ruby community they have a different approach on rubydoc, they tend to include examples + results in the methods comments. Like this:
http://www.ruby-doc.org/core/c...

I found it really useful :)
tcurdt

Mads, what do you consider "real documentation"? To me this really depends on the project. As for simple APIs like we have e.g. in jakarta commons I am more than fine with proper javdocs plus good examples. For bigger projects there is probably no way around additional documentation describing processes, ideas and component interactions. Sure!

Dave, my point is not to drop javadocs but instead use them properly! To me properly does not mean comment every single line of code or "document" every setter and getter. Better create an overall picture of what is going on.

Less is sometimes more!
Dave Brondsema

If you have a Java library that will be used by 3rd-party developers, it is very useful to have javadocs for the API. I do agree with most of your points, though.
Mads Toftum

Another unfortunate result of javadocs is what seem to be a tendency to use them as an excuse for real documentation.

Looking through the things on jakarta and related projects, there often seems to be an abundance of auto generated apidocs, but not much else (sorry if I offend anyone, but that's my general impression - not pointing fingers at any specific project).

Torsten Curdt’s weblog

Why JavaDocs suck