Javadoc评论和阻止评论？ [英] Javadoc comments vs block comments?

问题描述

在方法开头何时使用块注释是否合适？何时使用javadoc风格的注释是否合适？

在

Java程序可以有两种类型的
注释：实现注释和
文档注释。实现
注释是在C ++中找到的，其中
由 /*...*/ 和//分隔。
文档注释（称为doc
注释）仅限Java，并且
由 /**...*/ 。文档注释
可以使用
javadoc工具提取到HTML文件。

实现注释适用于
注释代码或评论
关于特定的实现。
文档注释意在描述代码的
规范，从
实现自由的角度。要成为
读取的开发者可能不
必须有源代码在
手。

所以，另一种方式来解释我的问题将是：当什么时候，方法值得一个规范的代码，从一个无实现的角度（Javadoc），而不是一个特定的实现的注释，反之亦然？

编辑：我想我没有正确地传达我的问题，基于

这里是我想知道的例子。

  / ** 
 * Javadoc在这里评论一般实现？ 
 * / 
 / * 
 *我现在应该为我的具体实现单独块注释吗？ 
 * / 
 public void foo（）
 {
 ... 
} 
  

两种不同的注释风格传达两种不同类型的信息。有没有情况下，方法应该有BOTH一个领先的javadoc注释和一个引导块注释？

甚至要求的灵感是Eclipse自动生成这个为我刚刚：

  / * 
 *（非Javadoc）
 * @ see my.package＃process ）
 * / 
  

我想这里有一些样式

解决方案

信息：类的用户

em>需要知道应该进入一个Javadoc注释。

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

很可能任何代码块（类，接口，字段，方法，构造函数...）

个人我倾向于写非常少的非Javadoc评论，因为我喜欢以自我记录的方式构建我的代码。

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?

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

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.

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?

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?

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

/*
 * (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.

解决方案

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

Info that a developer modifying a class needs 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 both a Javadoc comment and a normal comment block, when both publicly visible as well as internal documentaton is required.

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评论和阻止评论？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！