/** 和 /* 在 Java 注释中

Question

有什么区别

/**
 * comment
 *
 *
 */

和

/*
 * 
 * comment
 *
 */

在 Java 中？我应该什么时候使用它们？

Answer 1

第一种形式称为Javadoc。当您为代码编写由javadoc 工具生成的正式API 时，您可以使用它。例如，the Java 7 API page 使用 Javadoc 并由该工具生成。

您会在 Javadoc 中看到的一些常见元素包括：

• @param：用于指示传递给方法的参数，以及它们预期具有的值

• @return：这用于指示该方法将返回什么结果

• @throws：用于表示方法在某些输入的情况下抛出异常或错误

• @since：用于表示该类或函数最早可用的Java版本

例如，这里是 Integer 的 compare 方法的 Javadoc：

/**
 * Compares two {@code int} values numerically.
 * The value returned is identical to what would be returned by:
 * <pre>
 *    Integer.valueOf(x).compareTo(Integer.valueOf(y))
 * </pre>
 *
 * @param  x the first {@code int} to compare
 * @param  y the second {@code int} to compare
 * @return the value {@code 0} if {@code x == y};
 *         a value less than {@code 0} if {@code x < y}; and
 *         a value greater than {@code 0} if {@code x > y}
 * @since 1.7
 */
public static int compare(int x, int y) {
    return (x < y) ? -1 : ((x == y) ? 0 : 1);
}

第二种形式是块（多行）注释。如果您想在评论中包含多行，请使用此选项。

我会说你只想谨慎地使用后一种形式;也就是说，您不希望使用不描述方法/复杂函数应该具有的行为的块 cmets 使代码负担过重。

由于 Javadoc 在两者中更具描述性，并且您可以通过使用它来生成实际文档，因此使用 Javadoc 比简单的块 cmets 更可取。

Answer 2

对于Java编程语言，两者之间没有区别。 Java 有两种类型的 cmets：传统 cmets (/* ... */) 和行尾 cmets (// ...)。请参阅Java Language Specification。因此，对于 Java 编程语言，/* ... */ 和 /** ... */ 都是传统 cmets 的实例，它们在 Java 编译器中的处理方式完全相同，即它们被忽略（或更准确地说：它们被视为白色空间）。

但是，作为 Java 程序员，您不仅仅使用 Java 编译器。您使用整个工具链，其中包括例如编译器、IDE、构建系统等。其中一些工具对事物的解释与 Java 编译器不同。特别是，/** ... */ cmets 由 Javadoc 工具解释，该工具包含在 Java 平台 中并生成文档。 Javadoc 工具将扫描 Java 源文件并将/** ... */ 之间的部分解释为文档。

这类似于FIXME 和TODO 之类的标签：如果您包含// TODO: fix this 或// FIXME: do that 之类的注释，大多数IDE 会突出显示这些cmets，这样您就不会忘记它们。但对于 Java，它们只是 cmets。

Answer 3

首先是Javadoc cmets。它们可以由javadoc 工具处理，为您的类生成 API 文档。第二个是普通的块注释。

Answer 4

阅读3.7 of JLS 部分，了解您需要了解的有关 Java 中 cmets 的所有信息。

cmets有两种：

• /* 文字 */

传统注释：从 ASCII 字符 /* 到 ASCII 字符 */ 的所有文本都被忽略（如在 C 和 C++ 中）。

• //文字

行尾注释：从 ASCII 字符 // 到行尾的所有文本都被忽略（如在 C++ 中）。

---

关于您的问题，

第一个

/**
 *
 */

用于声明Javadoc Technology。

Javadoc 是一个解析声明和文档的工具 cmets 在一组源文件中并生成一组 HTML 页面 描述类、接口、构造函数、方法和字段。 您可以使用 Javadoc doclet 来定制 Javadoc 输出。一个 doclet 是 用 Doclet API 编写的程序，指定内容和 工具生成的输出格式。你可以写一个 doclet 生成任何类型的文本文件输出，例如 HTML、SGML、 XML、RTF 和 MIF。 Oracle 提供了一个标准的 doclet 用于生成 HTML 格式的 API 文档。 Doclet 也可以用来执行 与生成 API 文档无关的特殊任务。

有关Doclet 的更多信息，请参阅API。

第二个，正如 JLS 中清楚解释的那样，将忽略 /* 和 */ 之间的所有文本，因此用于创建多行 cmets。

---

您可能想了解的有关 Java 中 cmets 的其他一些信息

• 评论不嵌套。
• /* and */ 在以// 开头的 cmets 中没有特殊含义。
• // 在以/* or /** 开头的 cmets 中没有特殊含义。
• 词法语法意味着 cmets 不会出现在字符文字 (§3.10.4) 或字符串文字 (§3.10.5) 中。

因此，以下文本是一个完整的注释：

/* this comment /* // /** ends here: */

Answer 5

我认为现有答案不足以解决这部分问题：

我应该什么时候使用它们？

如果您正在编写一个将在您的组织内发布或重用的 API，您应该为每个 public 类、方法和字段以及 protected 方法和非final 班级。 Javadoc 应该涵盖不能通过方法签名传达的所有内容，例如前置条件、后置条件、有效参数、运行时异常、内部调用等。

如果您正在编写内部 API（由同一程序的不同部分使用的 API），Javadoc 可以说不那么重要。但是为了维护程序员的利益，您仍然应该为正确用法或含义不立即明显的任何方法或字段编写 Javadoc。

Javadoc 的“杀手级功能”在于它与 Eclipse 和其他 IDE 紧密集成。开发人员只需将鼠标指针悬停在标识符上即可了解他们需要了解的所有信息。不断参考文档成为有经验的 Java 开发人员的第二天性，这提高了他们自己代码的质量。如果您的 API 没有使用 Javadoc 进行记录，那么有经验的开发人员将不想使用它。

Answer 6

以下 Java 代码列表中的注释为灰色字符：

/** 
 * The HelloWorldApp class implements an application that
 * simply displays "Hello World!" to the standard output.
 */
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!"); //Display the string.
    }
}

Java语言支持三种cmets：

/* text */

编译器会忽略从/* 到*/ 的所有内容。

/** documentation */

这表示文档注释（简称文档注释）。编译器会忽略这种注释，就像它会忽略使用/* 和*/ 的cmets。 JDK javadoc 工具在准备自动生成的文档时使用 doc cmets。

// text

编译器会忽略从// 到行尾的所有内容。

现在关于什么时候应该使用它们：

当您想要注释一行代码时使用// text。

当您想要注释多行代码时使用/* text */。

当您想要添加一些有关可用于自动生成程序文档的程序的信息时，请使用/** documentation */。

Answer 7

第一个是用于您在类、接口、方法等之上定义的 Javadoc。您可以使用 Javadoc 作为名称建议来记录您的代码关于类的作用或方法的作用等并生成报告。

第二个是代码块注释。 例如，假设您有一些不希望编译器解释的代码块，然后使用代码块注释。

另一个是 // 您可以在语句级别使用它来指定接下来的代码行应该做什么。

还有一些类似//TODO，这将标志着你想稍后在那个地方做点什么

//FIXME 当你有一些临时解决方案但你想稍后访问并使其变得更好时可以使用。

希望对你有帮助

Answer 8

• 单条评论，例如：//comment
• 多行注释，例如：/* 注释 */
• javadoc 注释 例如：/** 注释 */

Answer 9

Java 支持两种类型的 cmets：

• /* multiline comment */ ：编译器忽略从/* 到*/ 的所有内容。评论可以跨越多行。

• // single line ：编译器忽略从// 到行尾的所有内容。

一些工具，例如 javadoc 使用特殊的多行注释来实现它们的目的。例如/** doc comment */ 是 javadoc 在准备自动生成的文档时使用的文档注释，但对于 Java，它是一个简单的多行注释。