Valuable Javadocs are hard to find. This blog post presents some really stupid, unnecessary and irritating Javadocs that I found when browsing some code.

All the examples presented in this blog post are real, but I changed the names of classes, methods and variables to protect the innocents. :)

I have tried to somehow categorize useless Javadocs into few types, not sure if it makes things better, as they are all useless, and that is their main feature.

DRY Principle? Never Heard Of!

The DRY principle (http://en.wikipedia.org/wiki/Don%27t_repeat_yourself) basically says that you should not repeat yourself. The following examples of Javadocs do not care about it at all, and merrily repeat what is obvious from code.

One example is the repetition of the class name. There are many variants of this useless documentation, for example:

/**
 * Authentication result.
 */
public class AuthenticationResult { ... }

This one is also worthless:

/**
 * Implementation of CoolInterface.
 */
public class CoolInterfaceImplementation implements CoolInterface { ... }

Documentation of getters/setters also fits nicely into this category. Really useless.

/**
 * @return Returns the xyz.
 */
public String getXyz() {
    return xyz;
}

/**
 * @param xyz
 *            The xyz to set.
 */
public void setXyz(String xyz) {
    this.xyz = xyz;
}

BTW. Is it Eclipse or IntelliJ IDEA which generates such silly Javadocs? If so, turn this feature off!

Nothing I Would Care About

Sometimes you can see how the developer forced him/herself to write something sensible ...and failed miserably. :)

/**
 * Constructor.
 */
public Resource() { ... }

/**
 * Constructor with fields.
 */
public Resource(String name, String location, String description) { ... }

Copy & Paste & Never Update

Sometimes Javadocs are simply there, because they were in another method. And so they came here when developer copied & pasted the code along with Javadocs. Of course, they were never updated to reflect the semantics of the new method. And now the documentation lies. Like this:

/**
 * This method always return ConverterMock or null. No exception is
 * expected.
 *
 * @return ConverterMock reference if found, null in other cases.
 */
public static String getProductByHolder(String holderId) {
    ProductLookupService c = new ProductLookupService();
    return c.lookupProduct(holderId);
}

Low Hanging Fruit

Sometime developer feels he/she should write some Javadocs. Then he/she chooses the most basic stuff to describe ...and completely ignores what should be really documented! (what the heck is mBit?!)

    /**
     * Constructor.
     */
    public Product() { ... }

    /**
     * Product name.
     */
    private String name;
    /**
     * Product description.
     */
    private String description;
    private double mBit;

As pointed out to me by Łukasz D. (thank you!) stuff like mBit may be some fundamental concept of the business domain, and is probably explained in detail in some other documentation (hm... is there any other documentation?). Maybe so, but anyway, to have an entry for name and no entry for mBit is kind of a cruel joke, don't you think?

Conclusions

What can I say? As proved by the examples above it is pretty simple to write Javadocs, and I would say it is even fun. I can do it, you can do it, his grandma can do it, and her cat can do it as well. So let us write more of this stuff, because that is what programming is all about! ;)