Should Javadoc comments be added to the implementation?

小开

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

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

小开

For the sake of generated javadoc yes it does matter. If you declare references to a concrete implementation using only the interface then it doesn't since interface's methods will be retrieved by the IDE.

小开

它在接口中生成一个到描述的链接。但是我认为添加一些关于实现的细节也是很好的。

小开

有些好的做法是

/**
* {@inheritDoc}
*/

作为实现的 javadoc (除非有关于实现细节的额外说明)。

小开

Sjoerd 正确地指出接口和实现都应该有 JavaDoc。接口 JavaDoc 应该定义方法的契约-方法应该做什么，接受什么输入，应该返回什么值，以及出错时应该做什么。

实现文档应该注明合同的扩展或限制，以及实现的适当细节，尤其是性能。

小开

最佳答案

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

如果你有一个重写的情况，你要复制任何文本，然后肯定不会。复制肯定会导致差异。因此，根据用户是在超类型中检查方法还是在子类型中检查方法，用户将对您的方法有不同的理解。使用 @inheritDoc或不提供文档-IDE 将采用最低可用文本在 Javadoc 视图中使用。

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

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

小开

通常，当您重写一个方法时，您会遵守在基类/接口中定义的约定，所以无论如何您都不希望更改原来的 javadoc。因此，其他答案中提到的 @inheritDoc或 @see标签的使用是不需要的，实际上只是代码中的一个噪音。所有合理的工具都按照指定的给你从超类或接口继承 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 工具总是显示某种类型的指定链接，您可以单击它来读取基类注释。把它们混在一起是没有意义的。