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 implementations when you auto generate comments. Shouldn't the concrete method have the description?

Answer 1

For methods that are implementation only (not overrides), sure, why not, especially if they are public.

If you have an overriding situation and you are going to replicate any text, then definitely not. Replication is a surefire way of causing discrepancies. As a result, users would have a different understanding of your method based on whether they examine the method in the supertype or the subtype. Use @inheritDoc or don't provide a documentation - The IDEs will take the lowest available text to use in their Javadoc view.

As an aside, if your overriding version adds stuff to the documentation of the supertype, you could be in a world of trouble. I studied this problem during my PhD and found that in general folks will never be aware of the extra information in the overriding version if they are invoking through a supertype.

Addressing this problem was one of the major feature of the prototype tool that I built - Whenever you invoked a method, you got an indication if its target or any potential overriding targets contained important information (e.g., a conflicting behavior). For instance, when invoking put on a map, you were reminded that if your implementation is a TreeMap, your elements need to be comparable.

Answer 2

Both the implementation and the interface should have javadoc. With some tools, you can inherit the documentation of the interface with the @inheritDoc keyword.

/**  * @inheritDoc  *  * This implementation is very slow when b equals 3.  */ public foo(int b) { ... }