Should Javadoc comments be added to the implementation?

Question

Is it correct practice to add Javadoc comments in the interface and add non-Javadoc comments in the implementation?

Most IDEs generate non-JavaDoc comments for imple

Answer 1

Generally, when you override a method, you adhere to the contract defined in the base class/interface, so you don't want to change the original javadoc anyhow. Therefore the usage of @inheritDoc or @see tag mentioned in other answers is not needed and actually only serves as a noise in the code. All sensible tools inherit method javadoc from the superclass or interface as specified here:

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

The fact that some tools (I'm looking at you, Eclipse!) generate these by default when overriding a method is only a sad state of things, but doesn't justify cluttering your code with useless noise.

---

There can of course be the opposite case, when you actually want to add a comment to the overriding method (usually some additional implementation details or making the contract a bit stricter). But in this case, you almost never want to do something like this:

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

Why? Because the inherited comment can possibly be very long. In such case, who will notice the extra sentence at the end of the 3 long paragraphs?? Instead, just write down the piece of your own comment and that's all. All the javadoc tools always show some kind of Specified by link which you can click to read the base class comment. There is no point in mixing them.