Comments on Overridden method in Java

Question

Should we comment the overridden method or not? If yes, then whether the comment will be a Java Doc or simple comment?

Answer 1

@SimonC's answer explains how the javadoc utility generates "inherited" documentation for overridden methods.

You can also put explicit javadocs in an override method and they will take precedence over the inherited javadocs. Furthermore, if you put the {@inheritDoc} tag in the override method's explicit javadocs, the inherited comments will be included at that point.

To answer this:

Should we comment the overridden method or not? If yes, then whether the comment will be a Java Doc or simple comment?

In my opinion, if the override method refines the documented semantics (contract) of the overridden method (or ... heaven forbid ... breaks the contract), then this deserves to be documented in the override method's javadocs. However, if the differences are merely "implementation details", then simple comments (or no comments) are more appropriate.

(However, the practice of including a "non-javadoc" comment that refers the reader back to the overridden method's javadoc is, IMO, a waste of screen real-estate ... when I am reading the source code.)

Answer 2

From How to Write Doc Comments for the Javadoc Tool :

Automatic re-use of method comments

You can avoid re-typing doc comments by being aware of how the Javadoc tool duplicates (inherits) comments for methods that override or implement other methods. This occurs in three cases: 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 In the first two cases, if a method m() overrides another method, The Javadoc tool will generate a subheading "Overrides" in the documentation for m(), with a link to the method it is overriding.

In the third case, if a method m() in a given class implements a method in an interface, the Javadoc tool will generate a subheading "Specified by" in the documentation for m(), with a link to the method it is implementing.

In all three of these cases, if the method m() contains no doc comments or tags, the Javadoc tool will also copy the text of the method it is overriding or implementing to the generated documentation for m(). So if the documentation of the overridden or implemented method is sufficient, you do not need to add documentation for m(). If you add any documentation comment or tag to m(), the "Overrides" or "Specified by" subheading and link will still appear, but no text will be copied.