Is it correct practice to add Javadoc comments in 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?

+4  A: 

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, very slow when b equals 3.
public foo(int b)
{ ... }

For the sake of generated javadoc yes it does matter. If you declare references to a concrete implementation using only the interface then it doesn't since interface's methods will be retrieved by the IDE.

Boris Pavlović
+3  A: 

@see generates a link to the description in the interface. But i think it is good to add some details about the implementation too.

IMO using [email protected]` linking to interface methods is a good practice and it is enough in most cases. When you copy javadoc from interface method to concrete implementation you just duplicate information and it can quickly become inconsistent. However, any additional information about the implementation should be added to javadoc.
The additional doc is not about copying the doc from the interface, but just to explain how you implement the method and stuff like that. With an interface doc, your explain what the results/objectives (application state or method return) whereas in your implementation it might be good to explain how you achieve this objectives.

Somewhat good practice is to put

 * [email protected]}

as implementation's javadoc (unless there's something extra to be explained about the implementation's details).

The point of having an interface is that the method can be implemented in multiple ways. If I am just going to inherit the comments, what is the point in having the comment in the implementation?
Vaishak Suresh

We use java doc in both situations.
In interfaces, javadoc is a must. Quite hard to use it, without any knowledge what it does.
In the implementation its useful for auto complete and new colleagues.

+1  A: 

Sjoerd correctly says that both interface and implementation should have JavaDoc. The interface JavaDoc should define the contract of the method - what the method should do, what inputs it takes, what values it should return, and what it should do in cases of error.

The implementation documentation should note extensions or restrictions on the contract, and also appropriate details of the implementation, especially performance.

+1  A: 

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.