Stop Writing Redundant Javadoc

I keep seeing this exact same Javadoc being written over and over again:

/**
 * A pizza delivery.
 *
 * @author jessewilson
 */
public class PizzaDelivery {

  ...

  /**
   * Sets the address of this PizzaDelivery.
   * 
   * @param address the address to set.
   */
  public void setAddress(Address address) {
    ...
  }
}

Naturally, this doc took the code author time to write. He typed 'address' an extra 3 times. But I'm not concerned with the author's time; he's got lots of free time on his hands. My problem is that he's wasting his team's time and hurting the code.

Redundant Javadoc decreases the signal-to-noise ratio of the code. It trains your team that documentation is just a hoop that needs to be jumped through. It shows that Javadoc is for writing, not for reading. And that you think it's okay to put zero thought into documentation.

If you have nothing nice* to say, say nothing. If your code style guide makes Javadoc mandatory, change the style guide. A well-chosen method or class name is often enough.

# posted by Jesse Wilson on Sunday, August 05, 2007