关于Java中重写方法的评论

Question

我们应该评论被覆盖的方法吗？如果是,那么评论是Java Doc还是简单评论？

Answer 1

@ SimonC的回答解释了javadoc实用程序如何为重写方法生成"继承"文档.

您还可以在显式方法中放置显式的javadoc,它们将优先于继承的javadoc.此外,如果将{@inheritDoc}标记放在override方法的显式javadoc中,那么将包含继承的注释.

要回答这个问题:

我们应该评论被覆盖的方法吗？如果是,那么评论是Java Doc还是简单评论？

在我看来,如果覆盖方法改进了被覆盖方法的文档化语义(契约)(或者......天堂禁止......打破了契约),那么这值得记录在覆盖方法的javadocs中.但是,如果差异仅仅是"实施细节",那么简单的评论(或没有评论)更合适.

(但是,当我阅读源代码时,包含一个"非javadoc"注释,将读者引回到被覆盖的方法的javadoc的做法,IMO,浪费屏幕空间......)

Answer 2

从如何编写Javadoc工具的Doc注释:

自动重复使用方法注释

您可以通过了解Javadoc工具如何复制(继承)覆盖或实现其他方法的方法的注释来避免重新键入文档注释.这种情况在三种情况下发生:当类中的方法覆盖超类中的方法时当接口中的方法覆盖超接口中的方法时类中的方法在接口中实现方法在前两种情况下,如果是方法m()重写另一个方法,Javadoc工具将在m()的文档中生成一个子标题"Overrides",其中包含指向它所覆盖的方法的链接.

在第三种情况下,如果给定类中的方法m()在接口中实现方法,则Javadoc工具将在m()的文档中生成子标题"Specified by",并带有指向它正在实现的方法的链接.

在所有这三种情况下,如果方法m()不包含文档注释或标记,则Javadoc工具还将复制它覆盖或实现的方法文本到m()的生成文档.因此,如果重写或实现的方法的文档已足够,则无需为m()添加文档.如果向m()添加任何文档注释或标记,则仍会显示"覆盖"或"指定者"子标题和链接,但不会复制任何文本.