是否应该将 Javadoc 注释添加到实现中？答案

【问题标题】：Should Javadoc comments be added to the implementation?是否应该将 Javadoc 注释添加到实现中？
【发布时间】：2011-03-04 22:24:42
【问题描述】：

在接口中添加Javadoc cmets，在实现中添加非Javadoc cmets是否正确做法？

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

【问题讨论】：

标签： java interface comments javadoc

【解决方案1】：

对于仅实现（而不是覆盖）的方法，当然，为什么不呢，尤其是如果它们是公共的。

如果您遇到最重要的情况并且要复制任何文本，那么绝对不会。复制是导致差异的可靠方法。因此，用户会根据他们是在超类型还是子类型中检查方法而对您的方法有不同的理解。使用@inheritDoc 或不提供文档 - IDE 将采用最低可用文本在其 Javadoc 视图中使用。

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

解决这个问题是我构建的原型工具的主要功能之一 - 每当您调用一个方法时，您都会得到一个指示，它的目标或任何潜在的覆盖目标是否包含重要信息（例如，冲突行为）。例如，当调用 put on a map 时，会提醒您，如果您的实现是 TreeMap，则您的元素需要具有可比性。

【讨论】：

您不知道在使用 TreeMap 时元素需要可比较吗？实现也不应该实现冲突的行为。
我认为这应该是正确答案stackoverflow.com/a/39981265/419516

【解决方案2】：

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

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

【讨论】：

“一些工具”到底是什么？它是开箱即用的还是绑定到某些特定插件的。
我知道 Eclipse 使用 {@inheritDoc} 并且只有当您没有首先有注释 @Override 时它才有效

【解决方案3】：

一些好的做法是把

/**
 * {@inheritDoc}
 */

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

【讨论】：

拥有接口的关键在于方法可以通过多种方式实现。如果我只是要继承 cmets，那么在实现中添加注释有什么意义？
我使用上面的标签，然后将任何额外的必需文档放在标签下面。

【解决方案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 工具总是显示某种 Specified by 链接，您可以单击该链接来阅读基类注释。混合它们是没有意义的。

【讨论】：

【解决方案5】：

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

【讨论】：

IMO 使用@see 链接到接口方法是一种很好的做法，在大多数情况下就足够了。当您将 javadoc 从接口方法复制到具体实现时，您只是复制了信息，它很快就会变得不一致。但是，有关实现的任何其他信息都应添加到 javadoc。
附加文档不是关于从界面复制文档，而只是解释如何实现方法和类似的东西。使用接口文档，您可以解释结果/目标（应用程序状态或方法返回），而在您的实现中，最好解释您如何实现这些目标。

【解决方案6】：

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

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

【讨论】：

【解决方案7】：

为了生成 javadoc，是的，这很重要。如果您仅使用接口声明对具体实现的引用，则不会，因为接口的方法将由 IDE 检索。

【讨论】：