是否应该在实现中添加 Javadoc 注释？
在接口中添加 Javadoc 注释并在实现中添加非 Javadoc 注释是否正确？
当您自动生成注释时，大多数 IDE 都会为实现生成非 JavaDoc 注释。具体方法不是应该有描述吗？
Is it correct practice to add Javadoc comments in the interface and add non-Javadoc comments in the implementation?
Most IDEs generate non-JavaDoc comments for implementations when you auto generate comments. Shouldn't the concrete method have the description?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（7）
对于仅实现（而不是覆盖）的方法，当然，为什么不呢，特别是如果它们是公共的。
如果您遇到压倒一切的情况并且要复制任何文本，那么绝对不会。复制是导致差异的必然方法。因此，根据用户是否检查超类型或子类型中的方法，他们会对您的方法有不同的理解。使用 @inheritDoc 或不提供文档 - IDE 将采用最低的可用文本在其 Javadoc 视图中使用。
顺便说一句，如果您的重写版本向超类型的文档中添加了内容，那么您可能会遇到麻烦。我在攻读博士学位期间研究了这个问题，发现一般来说，如果人们通过超类型调用，他们将永远不会意识到重写版本中的额外信息。
解决这个问题是我构建的原型工具的主要功能之一 - 每当您调用一个方法时，您都会得到一个指示，即它的目标或任何潜在的覆盖目标是否包含重要信息（例如，冲突的行为）。例如，当在地图上调用 put 时，系统会提醒您，如果您的实现是 TreeMap，则您的元素需要具有可比性。
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.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.
实现和接口都应该有 javadoc。使用某些工具，您可以使用@inheritDoc关键字继承接口的文档。
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（除非有关于实现细节的额外说明）。
Somewhat good practice is to put
as implementation's javadoc (unless there's something extra to be explained about the implementation's details).
通常，当您重写方法时，您会遵守基类/接口中定义的约定，因此无论如何您都不想更改原始 javadoc。因此，不需要使用其他答案中提到的
@inheritDoc或@see标签，实际上只是在代码中充当噪音。所有明智的工具都从指定的超类或接口继承方法 javadoc 此处：事实上，某些工具（我正在看着你，Eclipse！）在重写方法时默认生成这些内容，这只是一种悲伤的状态，但这并不能证明用无用的东西来混乱你的代码是合理的噪音。
当然，当您实际上想向重写方法添加注释时（通常是一些额外的实现细节或使契约更严格），可能会出现相反的情况。但在这种情况下，你几乎永远不想做这样的事情：
为什么？因为继承的注释可能会很长。这样的话，谁会注意到这三个长段最后多了一句？相反，只需写下您自己的评论即可。所有 javadoc 工具总是显示某种指定链接，您可以单击该链接来阅读基类注释。混合它们是没有意义的。
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: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.
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:
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 by link which you can click to read the base class comment. There is no point in mixing them.
@see它生成一个指向界面中描述的链接。但我认为添加一些有关实现的细节也很好。@seeIt generates a link to the description in the interface. But I think it is good to add some details about the implementation too.Sjoerd 正确地说接口和实现都应该有 JavaDoc。接口 JavaDoc 应该定义方法的契约 - 方法应该做什么、需要什么输入、应该返回什么值以及出现错误时应该做什么。
实施文件应注明合同的扩展或限制，以及实施的适当细节，尤其是绩效。
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.
The implementation documentation should note extensions or restrictions on the contract, and also appropriate details of the implementation, especially performance.
为了生成 javadoc，是的，这确实很重要。如果您仅使用接口声明对具体实现的引用，则不会，因为接口的方法将由 IDE 检索。
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.