是否应该将 Javadoc 注释添加到实现中?
在界面中添加 Javadoc 注释并在实现中添加非 Javadoc 注释的做法是否正确?
大多数 IDE 在自动生成注释时会为实现生成非 JavaDoc 注释。具体的方法难道不应该有描述吗?
在界面中添加 Javadoc 注释并在实现中添加非 Javadoc 注释的做法是否正确?
大多数 IDE 在自动生成注释时会为实现生成非 JavaDoc 注释。具体的方法难道不应该有描述吗?
对于仅实现(而不是重写)的方法,当然,为什么不实现,特别是如果它们是公共的。
如果你有一个压倒一切的情况,并且你要复制任何文本,那么绝对不是。复制是造成差异的必然方式。因此,用户对方法的理解会有所不同,具体取决于他们是检查超类型还是子类型中的方法。使用或不提供文档 - IDE 将采用最低的可用文本在其 Javadoc 视图中使用。@inheritDoc
顺便说一句,如果你的重写版本将内容添加到超类型的文档中,你可能会遇到麻烦。我在攻读博士学位期间研究了这个问题,发现一般来说,如果人们通过超类型调用,他们永远不会意识到覆盖版本中的额外信息。
解决这个问题是我构建的原型工具的主要功能之一 - 每当您调用方法时,您都会得到指示,如果它的目标或任何潜在的覆盖目标包含重要信息(例如,冲突的行为)。例如,当在地图上调用 put 时,有人提醒您,如果您的实现是 TreeMap,那么您的元素需要具有可比性。
实现和接口都应该有javadoc。使用某些工具,您可以使用@inheritDoc关键字继承界面的文档。
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }