java - 是否应该将 Javadoc 注释添加到实现中？

Question

在接口(interface)中添加Javadoc注释，在实现中添加非Javadoc注释是正确的做法吗？

当您自动生成注释时，大多数 IDE 会为实现生成非 JavaDoc 注释。具体方法不应该有描述吗？

Answer 1

对于仅实现(而不是覆盖)的方法，当然，为什么不呢，尤其是如果它们是公共(public)的。

如果您遇到最重要的情况并且要复制任何文本，那么绝对不会。复制是导致差异的可靠方法。因此，用户会根据他们是在父类(super class)型还是子类型中检查方法而对您的方法有不同的理解。使用 @inheritDoc 或不提供文档 - IDE 将采用最低可用文本在其 Javadoc View 中使用。

顺便说一句，如果您的覆盖版本将内容添加到父类(super class)型的文档中，您可能会遇到麻烦。我在攻读博士学位期间研究了这个问题，发现一般来说，如果人们通过父类(super class)型调用，他们永远不会知道覆盖版本中的额外信息。

解决这个问题是我构建的原型(prototype)工具的主要功能之一 - 每当您调用一个方法时，您都会得到一个指示，它的目标或任何潜在的覆盖目标是否包含重要信息(例如，冲突行为)。例如，当调用 put on a map 时，会提醒您，如果您的实现是 TreeMap，则您的元素需要具有可比性。