在接口中添加 Javadoc 注释并在实现中添加非 Javadoc 注释是正确的做法吗?
当您自动生成注释时,大多数 IDE 会为实现生成非 JavaDoc 注释。具体方法不应该有描述吗?
原文由 Vaishak Suresh 发布,翻译遵循 CC BY-SA 4.0 许可协议
在接口中添加 Javadoc 注释并在实现中添加非 Javadoc 注释是正确的做法吗?
当您自动生成注释时,大多数 IDE 会为实现生成非 JavaDoc 注释。具体方法不应该有描述吗?
原文由 Vaishak Suresh 发布,翻译遵循 CC BY-SA 4.0 许可协议
15 回答8.4k 阅读
8 回答6.2k 阅读
1 回答4k 阅读✓ 已解决
3 回答6k 阅读
3 回答2.2k 阅读✓ 已解决
2 回答3.1k 阅读
2 回答3.8k 阅读
对于仅实现(而非覆盖)的方法,当然,为什么不呢,特别是如果它们是公共的。
如果你有一个压倒一切的情况并且你打算复制任何文本,那么绝对不会。复制是造成差异的必经之路。因此,用户会对您的方法有不同的理解,这取决于他们检查的是超类型还是子类型中的方法。使用
@inheritDoc
或不提供文档 - IDE 将在其 Javadoc 视图中使用最少的可用文本。顺便说一句,如果您的覆盖版本向超类型的文档中添加内容,您可能会遇到麻烦。我在攻读博士学位期间研究了这个问题,发现如果人们通过超类型调用,通常他们永远不会意识到覆盖版本中的额外信息。
解决这个问题是我构建的原型工具的主要特性之一——每当您调用一个方法时,您都会得到一个指示,指示它的目标或任何潜在的覆盖目标是否包含重要信息(例如,冲突行为)。例如,在地图上调用 put 时,系统会提醒您,如果您的实现是 TreeMap,则您的元素需要具有可比性。