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

问题描述

在界面中添加Javadoc注释并在实现中添加非Javadoc注释是否正确做法?

Is it correct practice to add Javadoc comments in the 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 on a map 时，会提醒您，如果您的实现是 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屋！