Have you ever seen comments like these?

/** Status filter. */
private String statusFilter;

/**
 * Getter for statusFilter.
 *
 * @return the statusFilter.
 */
public String getStatusFilter() {
  return statusFilter;
}
I have seen plenty of such useless clutter lately. Why would you comment code lines that are self-documenting? Why would you write more comment lines than code lines? The answer here is: misguided style guides. While I’m a big fan of static code analysis tools, but some of the standard rules shipped with these products just don’t make sense. For example, Checkstyle wants you to comment every field, every constant, and every private method. I think the examples above illustrate why this is a bad idea. Useless comments hinder readability and increase maintenance costs. Even if your IDE assists you in creating most of the comments – what’s the added value in such automatically generated triviality? So my advice is:

  • Do comment interface (API) methods that have non-obvious behavior (unlike getters). Comment the design intent of public interfaces and classes, not their internal implementation. (This also helps in identifying violations of the Single Responsibility Principle: if you have to many “ands” in your description, the interface/class probably does too much.)
  • Use static analysis checks to check for comments, but disable the rules that don’t make sense.
  • Don’t comment implementation details like private methods. Instead, make your code self-documenting. Use descriptive names for fields, constants, variables and method names. Don’t be afraid of long names. If you feel the urge to separately comment blocks of your code, extract that block to a new method and name it like the comment you would have written.