在接口中添加Javadoc注释并在实现中添加非Javadoc注释是正确的做法吗？
大多数IDE会在您自动生成注释时为实现生成非JavaDoc注释。具体方法不应该有描述吗？
答案 0 :(得分：59)
对于仅实现的方法（不是覆盖），确定，为什么不，尤其是如果它们是公开的。
如果你有一个压倒一切的情况，并且你要复制任何文本，那么绝对不会。复制是造成差异的绝佳方式。因此，用户可以根据他们是否检查超类型或子类型中的方法，对您的方法有不同的理解。使用@inheritDoc或不提供文档 - IDE将在其Javadoc视图中使用最低的可用文本。
顺便说一句，如果你的重写版本在超类型的文档中添加了东西，那么你可能会遇到麻烦。我在博士期间研究了这个问题，发现如果他们通过超类型调用，一般人们永远不会知道覆盖版本中的额外信息。
解决这个问题是我构建的原型工具的主要特征之一 - 每当你调用一个方法时，你都会看到它的目标或任何潜在的覆盖目标是否包含重要信息（例如，冲突的行为）。例如，在调用put on map时，系统会提醒您，如果您的实现是TreeMap，则您的元素需要具有可比性。
答案 1 :(得分：24)
实现和接口都应该有javadoc。使用某些工具，您可以使用@inheritDoc关键字继承接口文档。
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }
答案 2 :(得分：20)
一些好的做法是放
/**
* {@inheritDoc}
*/
作为实现的javadoc（除非有更多关于实现细节的解释）。
答案 3 :(得分：14)
通常，当您覆盖方法时，您遵守基类/接口中定义的契约，因此您无论如何都不想更改原始的javadoc。因此，不需要在其他答案中提及的@inheritDoc或@see标记的使用，实际上仅作为代码中的噪声。所有敏感工具都从指定的here超类或接口继承方法javadoc：
Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:
- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface
事实上，某些工具（我正在看着你，Eclipse！）默认情况下，当覆盖一个方法只是一种令人悲伤的状态时会产生这些，但不能证明用无用的噪音混淆你的代码。
当然，当您真正想要为重写方法添加注释时，通常会出现相反的情况（通常是一些额外的实现细节或使合同更严格）。但在这种情况下，你几乎不想做这样的事情：
/**
* {@inheritDoc}
*
* This implementation is very, very slow when b equals 3.
*/
为什么呢？因为继承的评论可能很长。在这种情况下，谁会注意到3段长段末尾的额外句子？相反，只需写下你自己的评论，这就是全部。所有javadoc工具总是显示某种 Specified by 链接，您可以单击该链接来读取基类注释。将它们混合没有意义。
答案 4 :(得分：6)
@see它会在界面中生成指向描述的链接。但我认为最好添加一些有关实施的细节。
答案 5 :(得分：4)
Sjoerd正确地说接口和实现都应该有JavaDoc。接口JavaDoc应该定义方法的契约 - 方法应该做什么，它需要什么输入，它应该返回什么值，以及在出错时它应该做什么。
实施文档应注意合同的扩展或限制，以及实施的适当细节，尤其是性能。
答案 6 :(得分：0)
为了生成javadoc，它确实很重要。如果仅使用接口声明对具体实现的引用，则它不会，因为IDE将检索接口的方法。