Mudassir Mudassir - 4 months ago 9
Java Question

Comments on Overriden method in Java

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

Answer

@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.)

Comments