Do not use Javadoc

Javadoc is here to help. To understand what the code does and how it works? Right?

I don’t think so. I confuses the heck out of me in most cases.

When I look at code like

/**
* Version number of signature.
*/
public static final String SIGNATURE_VERSION = "1";

I get the feeling that the javadoc is pretty pointless. Well, the damn String is named what it is, how does the Javadoc help me here?

Remove it. If you don’t remove it you might end up with something like

/**
 * Version number of signature.
 */
public static final String SIGNATURE_VERSION_OLD = "1";

after a while. Uh, what does this mean now? The Javadoc did not change but the variable was renamed … hmm, where is the truth?

Another example of Javadoc just used to satisfy the coding guide lines of a project is:

/** The request. */
private final HttpServletRequest request;

/**
 * Constructor.
 *
 * @param request the request
 */
 public HttpParamSource(final HttpServletRequest request) {
…

I mean, come on, so much noise. Totally useless for the reader of the code. It destroys the flow of reading the code. Most of the time we are spending code reading (and trying to understand).

The problem with Javadoc is that it only helps in a very few cases (public api is one of them). Furthermore chances are that the Javadoc will not be updated during refactoring or by adding new functionality.

If you are trying to attempt to write a Javadoc think about the naming again. It is always a sign that something is not right. Why are you trying to document it? Does it more than you can describe in a name? Maybe you should split it?

Please, use only minimal Javadoc in your code. Thanks.