Pretty Useless Javadocs

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! ;)

DocCrap

This was so systemic at my old place of work , and it annoyed me so much that I wrote a tool to delete it all. It doesn't get your /** Constructor. */ case; patches welcome.

DocCrapTest on my git

DocCrapTest on GitHub

> Is it Eclipse or IntelliJ

> Is it Eclipse or IntelliJ IDEA which generates such silly Javadocs?
Not the IDEA, at least. It can insert a *tag* like @return, but not the text for a tag, of course.

Some projects policies

Some projects policies require javadoc on every public method. Some of these comments are probably result of such policy. What are you going to write on top of "public Resource()" if you have to? It creates the object ... really ... not much more.

You can even turn on warning 'public methods without javadoc'.

sometimes, yes

You are right, it may happen that such Javadocs appear because of such stupid policies imposed. But the examples I gathered are of different breed (AFAIK, the projects the code comes from had no such policies) - they are rather a result of the lack of experience (or cluelesness) of devs.

--
Cheers,
Tomek

JAutodoc

There is an eclipse plugin that generates comments for you :)
http://jautodoc.sourceforge.net/

This generates 'useless' comments in the form you just presented.

Anyway would be useful to have example of useful javadocs.
In general comments are another piece of code that needs maitenance, maybe is better to write so called self-documenting code? What do you think? Does it exist really?

Nice post

Self documenting code has its perks. For instance naming the parts of a dog tail, nose, ears, eyes etc is much better than naming them a, b, c and d respectively. That's when documenting will become necessary to explain what they mean.

On another note, the above are all examples on where comments are completely unnecessary. If someone does not know what a constructor looks like, he's going to have problems reading the code in any case. Personally, the places where I don't mind comments are when they describe difficult to understand algorithms or explain what a non-trivial function does if the usage is not obvious.

Personally I use comments mostly to remember why I solved a particular problem a certain way, especially when I've had a hard to find bug. In java.swing some components' functions need to be called in a certain order for the component to work properly and it is good to remember not to change the order.

(Although mostly excellent the java api is riddled with what could be defined as bad or useless comments. Look for instance at class java.awt.Color; is it really necessary to explain that the field static Color BLACK is The color black?)

self-documenting code is not enough

thx for information on jautodoc - so people would know to stay away of it :)

regarding the self-documenting code, I do not think it is 100% possible. What can not be really expressed within code are architectural or business decisions.

--
Cheers,
Tomek

What to document

When one writes any method documentation, one should document the purpose of the documentation, the preconditions on its arguments, the invariants the method will maintain, and the postconditions on the result and the objects.

If one is using a validator system like JSR 303, one can write code like

public Name(@NotNull @Size(max=20) firstName, @NotNull @Size(max=40) surName) {
this.firstName = firstName;
this.surName = surName;
}

Even if one doesn't actually configure a validator for the project, or uses AOP to validate, the annotations appear in the Javadoc pages, and a user has a fighting chance to understand the constraints on the constructor. There will be no need to add {@code firstName} must not be {@code null} to the @param tag.

Even private methods could have Javadoc, if only to document assumptions, techniques, and strategies. Why is the programmer using a LinkedList instead of an ArrayList? Why is this String not internationalized?

nice

the JSR 303 example is interesting, I haven't used it yet

BTW. I use tests to describe such constraints/invariants etc. Yeah, I believe tests are a valuable "live documentation" which is always up-to-date.

--
Cheers,
Tomek

JSR 303

JSR 303 defines the javax.validation package, and there are two implementations; the Hibernate Validator, and Apache BeanValidation. The difference between using these validators and using tests is that the validators run on demand, while testing input runs whoever someone constructs or mutates an instance. Consider the duplication in:

public Name(String givenName, String surName) {
  if (givenName == null) {
    throw new NullPointerException("Given name.");
  } else if (givenName.length() > 20) {
    // Prefer writing a StringTooLongException class.
    throw new IllegalArgumentException("Given name too long: " + givenName.length());
  } else {
    this.givenName = givenName;
  }
  //...
}
public void setGivenName(String givenName) {
  // If block from constructor nearly repeated.
  // Do not have the constructor call a public non-final method.
  // Somebody might override it.
  // But, do you really want setters?
}

Do you want to validate right away, or just when you use the Name instance? Will this make a UI too finicky? Also, what happens when your business rules change, and you need to change '20' to '30'?

We're using the Hibernate validator at my work project. It does very well. One can also override the annotations through a xml file to change the business rules. The annotations in the constructor are really for documentation only, but see below. In reality, one writes:

@NotNull
@Size(max=20)
public String getGivenName() {
  return givenName;
}

and then the call validator.validate(name) checks and returns a collection of errors. There's a glue project for Apache Wicket that turns this into Wicket validation errors; this cuts 50% of the work.

On the other hand, if you use AOP, either through AspectJ, or through Spring AOP, you can create pointcuts matching calls with annotated arguments, and before advice to check those arguments, possibly throwing a NPE or IAE. The advantage again is that you can get the boilerplate code out of the method calls. Of course, AOP will confuse junior developers. The Apache validator has a way to do this too, but AspectJ has other useful roles too.

JSR 303: http://jcp.org/en/jsr/detail?id=303

Apache BeanValidation: http://incubator.apache.org/bval/cwiki/index.html (may change--leaving incubator status)

Hibernate Validator: http://www.hibernate.org/subprojects/validator.html

AspectJ: http://www.eclipse.org/aspectj/. Also see AspectJ in Action, by Laddad, published by Manning.

Please comment using