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

Should Javadoc comments be added to the implementation?

提问by Vaishak Suresh

Is it correct practice to add Javadoc comments in the interface and add non-Javadoc comments in the implementation?

在接口中添加 Javadoc 注释并在实现中添加非 Javadoc 注释是正确的做法吗？

Most IDEs generate non-JavaDoc comments for implementations when you auto generate comments. Shouldn't the concrete method have the description?

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

采纳答案by Uri

For methods that are implementation only (not overrides), sure, why not, especially if they are public.

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

If you have an overriding situation and you are going to replicate any text, then definitely not. Replication is a surefire way of causing discrepancies. As a result, users would have a different understanding of your method based on whether they examine the method in the supertype or the subtype. Use @inheritDocor don't provide a documentation - The IDEs will take the lowest available text to use in their Javadoc view.

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

As an aside, if your overriding version adds stuff to the documentation of the supertype, you could be in a world of trouble. I studied this problem during my PhD and found that in general folks will never be aware of the extra information in the overriding version if they are invoking through a supertype.

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

Addressing this problem was one of the major feature of the prototype tool that I built - Whenever you invoked a method, you got an indication if its target or any potential overriding targets contained important information (e.g., a conflicting behavior). For instance, when invoking put on a map, you were reminded that if your implementation is a TreeMap, your elements need to be comparable.

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

回答by Sjoerd

Both the implementation and the interface should have javadoc. With some tools, you can inherit the documentation of the interface with the @inheritDoc keyword.

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

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

回答by Boris Pavlovi?

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.

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

回答by redben

@see It generates a link to the description in the interface. But I think it is good to add some details about the implementation too.

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

回答by Vanya

Somewhat good practice is to put

一些好的做法是把

/**
 * {@inheritDoc}
 */

as implementation's javadoc (unless there's something extra to be explained about the implementation's details).

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

回答by DJClayworth

Sjoerd correctly says that both interface and implementation should have JavaDoc. The interface JavaDoc should define the contract of the method - what the method should do, what inputs it takes, what values it should return, and what it should do in cases of error.

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

The implementation documentation should note extensions or restrictions on the contract, and also appropriate details of the implementation, especially performance.

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

回答by Natix

Generally, when you override a method, you adhere to the contract defined in the base class/interface, so you don't want to change the original javadoc anyhow. Therefore the usage of @inheritDocor @seetag mentioned in other answers is not needed and actually only serves as a noise in the code. All sensible tools inherit method javadoc from the superclass or interface as specified here:

通常，当您覆盖一个方法时，您会遵守基类/接口中定义的契约，因此无论如何您都不想更改原始 javadoc。因此，不需要其他答案中提到的@inheritDocor@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

The fact that some tools (I'm looking at you, Eclipse!) generate these by default when overriding a method is only a sad state of things, but doesn't justify cluttering your code with useless noise.

某些工具（我正在看着你，Eclipse！）在覆盖方法时默认生成这些这一事实只是一种可悲的状态，但并不能证明用无用的噪音干扰您的代码是合理的。

---

---

There can of course be the opposite case, when you actually want to add a comment to the overriding method (usually some additional implementation details or making the contract a bit stricter). But in this case, you almost never want to do something like this:

当然也可能有相反的情况，当您实际上想向覆盖方法添加注释时（通常是一些额外的实现细节或使合同更严格一些）。但在这种情况下，你几乎不想做这样的事情：

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

Why? Because the inherited comment can possibly be very long. In such case, who will notice the extra sentence at the end of the 3 long paragraphs?? Instead, just write down the piece of your own comment and that's all. All the javadoc tools always show some kind of Specified bylink which you can click to read the base class comment. There is no point in mixing them.

为什么？因为继承的注释可能很长。在这种情况下，谁会注意到3长段末尾的额外句子？？相反，只需写下您自己的评论，仅此而已。所有 javadoc 工具总是显示某种Specified by链接，您可以单击该链接阅读基类注释。混合它们是没有意义的。