Java注释中的/ **和/ *


190

之间有什么区别

/**
 * comment
 *
 *
 */

/*
 * 
 * comment
 *
 */

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

Answers:


242

第一种形式称为Javadoc。在为javadoc工具编写由该工具生成的形式化API时,可以使用它。例如,Java 7 API页面使用Javadoc并由该工具生成。

您将在Javadoc中看到一些常见的元素,包括:

  • @param:用于指示将哪些参数传递给方法,以及它们应具有的值

  • @return:用于指示该方法将返回的结果

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

  • @since:用于指示此类或函数可用于的最早的Java版本

例如,以下是Javadoc的compare方法Integer

/**
 * 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);
}

第二种形式是块(多行)注释。如果要在注释中包含多行,请使用此选项。

我会说,你只需要使用后者的形式谨慎 ; 也就是说,您不想用不描述方法/复杂函数应该具有的行为的块注释来使代码负担重。

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


35
使用Javadoc而不是简单的块注释的另一个好处是,当您将Javadoc注释放在Java元素(例如方法签名,字段声明,类等)之前时,这将启用IDE-至少可以肯定使用Eclipse。 -在您对该Java元素的引用上移动光标(或用鼠标悬停)时显示注释(例如,在工具提示中)。
SantiBailors,2015年

可以使用Java文档注释作为变量吗?
the_prole

@the_prole:可以,但是除非包含在Constants包中,否则我看不出太多的价值。即使这样,在我的经验中,内联评论也更有价值。
Makoto

136

对于Java 编程语言两者之间没有区别。Java有两种类型的注释:传统注释(/* ... */)和行尾注释(// ...)。请参阅Java语言规范。因此,对于Java编程语言,两者/* ... *//** ... */都是传统注释的实例,并且它们都被Java编译器完全相同地对待,即,它们被忽略(或更正确地说:它们被视为空白)。

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

这类似于标签如FIXMEand TODO:如果您包含诸如// TODO: fix this或的注释// FIXME: do that,则大多数IDE都会突出显示此类注释,以使您不会忘记它们。但是对于Java,它们只是注释。


48
+1是重要的区分,Javadoc语法不是该语言的一部分,目前尚无其他答案。
克里斯·海斯

1
这就是为什么您可以拥有一个在Maven中可以正常编译的项目,但是一旦决定附加JavaDocs,它就会开始抱怨,因为该javadoc工具无法解释某些内容。
曼队长

19

首先是Javadoc注释。可以使用该javadoc工具对其进行处理,以为您的类生成API文档。第二个是普通的块注释。


14

阅读JLS的3.7节很好地解释了有关Java注释的所有知识。

有两种注释:

  • / *文字* /

传统注释:从ASCII字符/ *到ASCII字符* /的所有文本都将被忽略(与C和C ++一样)。

  • //文本

行尾注释:从ASCII字符//到行尾的所有文本都将被忽略(与C ++中一样)。


关于你的问题

第一个

/**
 *
 */

用于声明Javadoc技术

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

有关更多信息,Doclet请参阅API

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


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

  • 注释不嵌套。
  • /* and */以开头的注释没有特殊含义//
  • //以开头的注释没有特殊含义/* or /**
  • 词汇语法意味着注释不会出现在字符文字(第3.10.4节)或字符串文字(第3.10.5节)之内。

因此,以下文本是一个完整的注释:

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

8

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

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

如果要编写将在组织内发布或重用的API,则应为每个public类,方法和字段以及protectedfinal类的方法和字段编写全面的Javadoc注释。Javadoc应该涵盖方法签名无法传达的所有内容,例如前置条件,后置条件,有效参数,运行时异常,内部调用等。

如果您正在编写内部API(同一程序的不同部分使用的内部API),那么Javadoc的重要性可能会降低。但是,为了维护程序员的利益,您仍然应该为任何方法或字段(其用法或含义不立即显而易见)编写Javadoc。

Javadoc的“杀手级功能”是它与Eclipse和其他IDE紧密集成。开发人员只需将鼠标指针悬停在标识符上即可了解他们需要了解的所有内容。对于经验丰富的Java开发人员而言,不断引用文档已成为其第二天性,从而提高了他们自己代码的质量。如果您的API未随Javadoc一起记录,那么经验丰富的开发人员将不希望使用它。


4

以下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语言支持三种注释:

/* text */

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

/** documentation */

这表示文档注释(简称doc注释)。编译器会忽略此类注释,就像它会忽略使用/*和的注释一样*/。JDK javadoc工具在准备自动生成的文档时使用doc注释。

// text

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

现在,考虑何时使用它们:

使用// text时,您要评论的一行代码。

使用/* text */时,您要评论的多行代码。

使用/** documentation */ 时,你会想加入,可用于自动生成程序文档的程序的一些信息。


3

第一个是在类,接口,方法等顶部定义的Javadoc。您可以使用Javadoc作为名称建议,以记录有关类做什么或方法做什么的代码,并生成报告。

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

另一个是//您可以在语句级别使用它来指定代码的后续行应该执行的操作。

还有一些其他的东西,例如// TODO,这将标记您以后要在该位置做某事

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

希望这可以帮助


0
  • 单个注释,例如://注释
  • 多行注释,例如:/ *评论* /
  • javadoc注释,例如:/ **注释* /

4
这不会在现有答案上添加任何内容。
shmosel

1
@ shmosel不,它总结了您。
挪威

-2

Java支持两种类型的注释:

  • /* multiline comment */:编译器将忽略从/*到的所有内容*/。注释可以跨越多行。

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

一些工具(例如javadoc)出于其目的使用特殊的多行注释。例如/** doc comment */,javadoc在准备自动生成的文档时使用了文档注释,但是对于Java来说,这是一个简单的多行注释。


12
Java语言仅支持两种类型的注释。形式的注释/** .. */只是常规的多行注释,并且其中的第一个字符恰好是星号。
克里斯·海斯
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.