Javadoc 注释与块注释？

Javadoc comments vs block comments?

提问by Tony Stark

When is it appropriate to use a block comment at the beginning of methods, and when is it appropriate to use a javadoc-style comment?

什么时候在方法的开头使用块注释合适，什么时候使用 javadoc 风格的注释合适？

From the "Comments" section of the Java style guide, I found this:

从Java 风格指南的“评论”部分，我发现了这一点：

Java programs can have two kinds of comments: implementation comments and documentation comments. Implementation comments are those found in C++, which are delimited by /*...*/, and //. Documentation comments (known as "doc comments") are Java-only, and are delimited by /**...*/. Doc comments can be extracted to HTML files using the javadoc tool.

Implementation comments are meant for commenting out code or for comments about the particular implementation. Doc comments are meant to describe the specification of the code, from an implementation-free perspective. to be read by developers who might not necessarily have the source code at hand.

Java 程序可以有两种注释：实现注释和文档注释。实现注释是在 C++ 中找到的注释，由/*...*/, 和 //分隔。文档注释（称为“文档注释”）仅适用于 Java，并以/**...*/. 可以使用 javadoc 工具将文档注释提取到 HTML 文件中。

实现注释用于注释掉代码或关于特定实现的注释。文档注释旨在从无实现的角度描述代码规范。供那些不一定手头有源代码的开发人员阅读。

So, another way to phrase my question would be: When do methods deserve a specification of the code, from an implementation-free perspective (Javadoc) instead of a comment about a particular implementation, and vice versa? Would an interface get javadoc comments, while the implementations get block comments?

所以，表达我的问题的另一种方式是：从无实现的角度（Javadoc）而不是关于特定实现的评论，方法什么时候应该得到代码规范，反之亦然？接口会得到 javadoc 注释，而实现会得到块注释吗？

edit:I think I am not conveying my question correctly, based on the answers thus far.

编辑：根据迄今为止的答案，我认为我没有正确表达我的问题。

Here's an example of what I want to know.

这是我想知道的一个例子。

/**
 * Javadoc comment here about general implementation?
 */
/*
 * Should I now have a separate block comment for my specific implementation?
 */
public void foo()
{
...
}

The two different comment styles convey two different types of information. Are there cases when methods should have BOTH a leading javadoc comment, and a leading block comment?

两种不同的评论风格传达了两种不同类型的信息。是否存在方法应该同时具有前导 javadoc 注释和前导块注释的情况？

The inspiration for even asking is that Eclipse auto-generated this for me just now:

甚至询问的灵感是 Eclipse 刚刚为我自动生成了这个：

/*
 * (non-Javadoc)
 * @see my.package#process()
 */

And I figured there is some sort of styling going on here that isn't declared specifically in the comment specifications I link to above.

我认为这里有某种样式没有在我上面链接的评论规范中特别声明。

采纳答案by Joachim Sauer

Info that the user of a classneeds to know should go into a Javadoc comment.

类的用户需要知道的信息应该放在 Javadoc 注释中。

Info that a developer modifying a classneeds to know go into a normal comment (block or line).

修改类的开发人员需要知道的信息进入普通注释（块或行）。

And it's very possible that any block of code (class, interface, field, method, constructor, ...) can have botha Javadoc comment and a normal comment block, when both publicly visible as well as internal documentaton is required.

当需要公开可见和内部文档时，任何代码块（类、接口、字段、方法、构造函数等）都可以同时具有 Javadoc 注释和普通注释块。

Personally I tend towards writing very little non-Javadoc comments, because I prefer to structure my code in a way that it's self-documenting.

就我个人而言，我倾向于编写很少的非 Javadoc 注释，因为我更喜欢以一种自我记录的方式来构建我的代码。

回答by Vivien Barousse

In my opinion, Javadoc comments are comments you write to the people who use your code, and who invoke your methods.

在我看来，Javadoc 注释是您写给使用您的代码和调用您的方法的人的注释。

Javadoc comments are more focused on the parameters of the methods, what your method will return depending on the parameters you give to your methods.

Javadoc 注释更侧重于方法的参数，根据您为方法提供的参数，您的方法将返回什么。

Block comments are internal comments, comments you write for people maintaining your code.

块注释是内部注释，是您为维护代码的人员编写的注释。

Block comments are important to understand how the code works, why it works and which are the operations used to do the actual work.

块注释对于理解代码如何工作、为什么工作以及用于执行实际工作的操作很重要。

回答by musiKk

In my opinion it makes no sense to put block comments at the top of the method (well, never say never but at least most of the time). Javadoc comments on interface methods specify the contract, on class methods they tell about the implementation so a user can decide which class to use if there are multiple classes implementing a single interface. Think about the Listinterface; the implementations ArrayListand LinkedListare appropriate in different use cases so their respective documentations might explain about their pros and cons.

在我看来，将块注释放在方法的顶部是没有意义的（好吧，永远不要说永远，但至少在大多数时候）。Javadoc 对接口方法的注释指定了契约，它们在类方法上讲述了实现，因此如果有多个类实现单个接口，用户可以决定使用哪个类。考虑List界面；的实现ArrayList和LinkedList在不同的使用情况适当使各自的单证可能对他们的利弊解释。

I inline block comments about very specific things. I want the implementation specific doc directly where the implementation is. Of course you should use them as rare as possible. Use expressive variable and method names and they automatically add low level documentation.

我内联块评论关于非常具体的事情。我希望直接在实现所在的位置获得特定于实现的文档。当然，您应该尽可能少地使用它们。使用富有表现力的变量和方法名称，它们会自动添加低级文档。

The automatically generated block comments of Eclipse are for you to fill out and potentially make them Javadoc comments by adding the missing asterisk. I don't know exactly in which cases they appear but one is when you extract an interface from an existing class. Then the Javadoc from the class goes to the interface method and the class method gets the block comment. The reasoning behind this is that often when implementing an interface you don't really have that much to add. Again I use Listas an example. The size()method wouldn't need any more documentation in the ArrayListand LinkedListimplementations. They have nothing of value to add. Of course this example is contrived because the actual implementations (at least of OpenJDK) dohave Javadocs but I see no need for that and indeed the don't add anything of value. Worse yet they provide even lessinformation than the interface documentation.

Eclipse 自动生成的块注释供您填写，并可能通过添加缺少的星号使它们成为 Javadoc 注释。我不知道它们究竟在哪些情况下出现，但一种是当您从现有类中提取接口时。然后类中的 Javadoc 转到接口方法，类方法获取块注释。这背后的原因是，通常在实现接口时，您实际上并没有太多要添加的内容。我再次List举个例子。该size()方法在ArrayList和LinkedList实现中不需要任何更多文档。他们没有任何可添加的价值。当然这个例子是人为的，因为实际的实现（至少OpenJDK的的）做有 Javadocs，但我认为没有必要，而且确实没有增加任何价值。更糟糕的是，它们提供的信息甚至比接口文档还要少。