Java 中 Overridden 方法的评论
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/4310858/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Comments on Overridden method in Java
提问by Mudassir
Should we comment the overridden method or not? If yes, then whether the comment will be a Java Doc or simple comment?
我们是否应该评论被覆盖的方法？如果是，那么评论是 Java Doc 还是简单评论？
回答by Stephen C
@SimonC's answer explains how the javadoc utility generates "inherited" documentation for overridden methods.
@SimonC 的回答解释了 javadoc 实用程序如何为重写的方法生成“继承”文档。
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.
您还可以将显式 javadoc 放在覆盖方法中，它们将优先于继承的 javadoc。此外，如果您将{@inheritDoc}标记放在 override 方法的显式 javadoc 中，那么继承的注释将被包含在内。
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?
我们是否应该评论被覆盖的方法？如果是，那么评论是 Java Doc 还是简单评论？
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.
在我看来，如果覆盖方法改进了被覆盖方法的文档语义（契约）（或者……天堂禁止……破坏契约），那么这应该被记录在覆盖方法的 javadoc 中。但是，如果差异仅仅是“实现细节”，那么简单的注释（或不注释）更合适。
(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.)
（但是，在我阅读源代码时，包含一个“非 javadoc”注释，将读者引回到重写方法的 javadoc 的做法是，IMO，浪费屏幕空间……。）
回答by SimonC
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.
方法注释的自动重用
您可以通过了解 Javadoc 工具如何复制（继承）覆盖或实现其他方法的方法的注释来避免重新输入文档注释。这在三种情况下发生： 当类中的方法覆盖超类中的方法时 当接口中的方法覆盖超接口中的方法时 当类中的方法实现接口中的方法时 在前两种情况下，如果方法 m() 覆盖另一个方法，Javadoc 工具将在 m() 的文档中生成一个子标题“覆盖”，并带有指向它覆盖的方法的链接。
在第三种情况下，如果给定类中的方法 m() 实现了接口中的方法，Javadoc 工具将在 m() 的文档中生成一个子标题“指定者”，并带有指向它正在实现的方法的链接.
在所有这三种情况下，如果方法 m() 不包含 doc 注释或标签，Javadoc 工具还会将它覆盖或实现的方法的文本复制到为 m() 生成的文档中。因此，如果重写或实现的方法的文档就足够了，则不需要为 m() 添加文档。如果您向 m() 添加任何文档注释或标签，“覆盖”或“指定者”副标题和链接仍将出现，但不会复制任何文本。
