是否应该将 Javadoc 注释添加到实现中?

新手上路,请多包涵

在接口中添加 Javadoc 注释并在实现中添加非 Javadoc 注释是正确的做法吗?

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

原文由 Vaishak Suresh 发布,翻译遵循 CC BY-SA 4.0 许可协议

阅读 488
2 个回答

对于仅实现(而非覆盖)的方法,当然,为什么不呢,特别是如果它们是公共的。

如果你有一个压倒一切的情况并且你打算复制任何文本,那么绝对不会。复制是造成差异的必经之路。因此,用户会对您的方法有不同的理解,这取决于他们检查的是超类型还是子类型中的方法。使用 @inheritDoc 或不提供文档 - IDE 将在其 Javadoc 视图中使用最少的可用文本。

顺便说一句,如果您的覆盖版本向超类型的文档中添加内容,您可能会遇到麻烦。我在攻读博士学位期间研究了这个问题,发现如果人们通过超类型调用,通常他们永远不会意识到覆盖版本中的额外信息。

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

原文由 Uri 发布,翻译遵循 CC BY-SA 3.0 许可协议

实现和接口都应该有 javadoc。借助一些工具,您可以使用@inheritDoc 关键字来继承接口的文档。

 /**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

原文由 Sjoerd 发布,翻译遵循 CC BY-SA 3.0 许可协议

撰写回答
你尚未登录,登录后可以
  • 和开发者交流问题的细节
  • 关注并接收问题和回答的更新提醒
  • 参与内容的编辑和改进,让解决方法与时俱进
推荐问题