应该将JavaDoc注释添加到实现中 [英] Should JavaDoc comments be added to the implementation

问题描述

在Interface中添加Javadoc注释并在实现中添加非Javadoc注释是否正确？

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

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

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

推荐答案

对于只实现（不覆盖）的方法， ，特别是如果他们是公开的。

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

如果你有一个凌驾的情况，你要复制任何文本，那么绝对不是。复制是造成差异的确定的方式。因此，用户将根据他们是否检查超类型或子类型中的方法，对您的方法有不同的理解。使用 @inheritDoc 或不提供文档 - IDE将使用最低可用文本在Javadoc视图中使用。

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 @inheritDoc or 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.

解决这个问题是我构建的原型工具的一个主要特点 - 每当你调用一个方法，你得到一个指示，如果其目标或任何潜在的首要目标包含重要信息（例如，冲突行为）。例如，当在地图上调用put时，会提醒您，如果您的实现是TreeMap，您的元素需要具有可比性。

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注释添加到实现中的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！