对 Java 中被覆盖的方法的评论

@SimonC的答案解释了javadoc实用程序如何为重写的方法生成“继承”文档。

您还可以将显式 javadocs 放在重写方法中，它们将优先于继承的 javadocs。此外，如果将标记放在重写方法的显式 javadocs 中，则此时将包含继承的注释。{@inheritDoc}

要回答这个问题：

我们是否应该注释被覆盖的方法？如果是，那么注释是Java文档还是简单注释？

在我看来，如果覆盖方法细化了重写方法的记录语义（合同）（或...天堂禁止...打破契约），那么这值得记录在重写方法的javadocs中。但是，如果差异仅仅是“实现细节”，那么简单的注释（或没有注释）更合适。

（但是，包含“非javadoc”注释的做法是将读者引回被覆盖方法的javadoc，IMO浪费屏幕空间......当我阅读源代码时。

从如何为 Javadoc 工具编写文档注释：

自动重用方法注释

通过了解 Javadoc 工具如何复制（继承）重写或实现其他方法的方法的注释，可以避免重新键入文档注释。这种情况在以下三种情况下发生： 当类中的方法重写超类中的方法时 接口中的方法覆盖超接口中的方法 当类中的方法在接口中实现方法在前两种情况下，如果方法 m（） 重写另一个方法，Javadoc 工具将在 m（） 的文档中生成一个副标题“Overrides”， 带有指向它所覆盖的方法的链接。

在第三种情况下，如果给定类中的方法 m（） 在接口中实现了一个方法，Javadoc 工具将在 m（） 的文档中生成一个副标题“指定者”，并带有指向它正在实现的方法的链接。

在所有这三种情况下，如果方法 m（） 不包含文档注释或标记，Javadoc 工具还会将其覆盖或实现的方法的文本复制到生成的 m（） 文档中。因此，如果重写或实现的方法的文档就足够了，则不需要为m（）添加文档。如果向 m（） 添加任何文档注释或标记，仍将显示“覆盖”或“指定者”子标题和链接，但不会复制任何文本。