java应该在实现中添加Javadoc注释吗？

Question

在接口中添加Javadoc注释和在实现中添加非Javadoc注释是否正确

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

Answer 1

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

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

Answer 2

有些好的做法是

/**
 * {@inheritDoc}
 */

作为实现的javadoc（除非对实现的细节有额外的解释）

Answer 3

@see它会生成一个指向界面中描述的链接。但我认为，添加一些关于实施的细节也是很好的

Answer 4

通常，当您重写一个方法时，您遵守在基类/接口中定义的契约，因此您无论如何都不想更改原始的javadoc。因此，在其他答案中提到的@inheritDoc或@see标记的使用是不必要的，实际上只是作为代码中的噪声。所有合理的工具都从超类或接口继承方法javadoc，如指定的here：

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工具总是显示由链接指定的某种，您可以单击该链接来阅读基类注释。把它们混在一起没有意义

Answer 5

Sjoerd正确地说接口和实现都应该有JavaDoc。接口JavaDoc应该定义方法的契约——方法应该做什么，它接受什么输入，它应该返回什么值，以及在发生错误时应该做什么

实施文件应注明合同的扩展或限制，以及实施的适当细节，尤其是履约情况

Answer 6

对于只实现（而不是重写）的方法，当然可以，为什么不呢，特别是如果它们是公共的

如果你有一个压倒一切的情况，你要复制任何文本，那么肯定不是。复制肯定会导致差异。因此，用户对方法的理解可能会有所不同，这取决于他们是在超类型还是子类型中检查方法。使用@inheritDoc或不提供文档-IDE将在其Javadoc视图中使用最低可用文本

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

解决这个问题是我构建的原型工具的主要功能之一——无论何时调用一个方法，都会得到一个指示，表明其目标或任何潜在的重写目标是否包含重要信息（例如，冲突行为）。例如，当调用映射上的put时，会提醒您，如果您的实现是树映射，那么您的元素需要具有可比性