Should Javadoc implementation comments be added?

Question

Is it a good practice to add Javadoc comments to the interface and add non-Javadoc comments to the implementation?

Most IDEs generate non-JavaDoc comments for implementations when automatically creating comments. Should a particular method have a description?

Answer 1

For methods that are only an implementation (not overriding), of course, why not, especially if they are publicly available.

If you have a situation with excess, and you are going to copy any text, then definitely not. Replication is the right way to create discrepancies. As a result, users will have a different understanding of your method based on whether they learn the method in a supertype or subtype. Use @inheritDoc or do not provide documentation. The IDE will use the lowest available text for use in the Javadoc view.

Aside, if your overriding version adds material to the supertype documentation, you might find yourself in a world of problems. I studied this problem during my PhD and found that in general people will never know about additional information in an overridden version if they are called through a supertype.

The solution to this problem was one of the main features of the prototype I created - every time you called a method, you were instructed that its purpose or any potential overriding goals contained important information (for example, conflicting behavior). For example, when calling on a map, you were reminded that if your implementation is a TreeMap, your elements should be comparable.

Answer 2

Both the implementation and the interface must have javadoc. With some tools, you can inherit interface documentation using the @inheritDoc keyword.

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

Answer 3

To some extent, it’s good practice to put

 /** * {@inheritDoc} */ 

like javadoc implementation (if there is no details about implementation details).

Answer 4

@see Creates a description link in the interface. But I think it is also useful to add some details about this implementation.

Answer 5

Typically, when you override a method, you stick to the contract defined in the base class / interface, so you don't want to change the original javadoc. Therefore, the use of the @inheritDoc or @see tag mentioned in other answers is not required and in fact serves only as noise in the code. All reasonable tools inherit the javadoc method from a superclass or interface, as indicated 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 them by default when overriding a method is just a sad state of things, but does not justify cluttering your code with useless noise.

---

Of course, there may be the opposite case when you really want to add a comment to the override method (as a rule, some additional implementation details or more stringent contract conditions). 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 an inherited comment can be very long. In that case, who will notice the additional sentence at the end of the three long paragraphs? Instead, just write a slice of your own comment and that’s it. All javadoc tools always show some link by link, which you can click to read the comment on the base class. It makes no sense to mix them.

Answer 6

Sjoerd correctly says that both the interface and the implementation must have JavaDoc. The JavaDoc interface must define the method contract - what the method should do, what data it takes, what values ​​it should return, and what it should do in case of errors.

Implementation documentation should include extensions or limitations to the contract, as well as relevant implementation details, especially performance.

Answer 7

For the sake of generating javadoc, yes, that matters. If you declare references to a specific implementation using only the interface, this does not happen, since the interface tools will be extracted using the IDE.