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?
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.
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)
{ ... }
Somewhat good practice is to put
/**
* {@inheritDoc}
*/
as implementation's javadoc (unless there's something extra to be explained about the implementation's details).
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.
@see It generates a link to the description in the interface. But I think it is good to add some details about the implementation too.
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.
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.
