有什么区别
/**
* comment
*
*
*/
and
/*
*
* comment
*
*/
在Java中?什么时候使用它们?
有什么区别
/**
* comment
*
*
*/
and
/*
*
* comment
*
*/
在Java中?什么时候使用它们?
第一种形式称为Javadoc。当您为代码编写由javadoc工具生成的正式api时,可以使用它。例如,Java 7 API页面使用Javadoc,并由该工具生成。
你在Javadoc中看到的一些常见元素包括:
@param:用来指示传递给方法的参数是什么,以及它们期望有什么值 @return:用于指示方法将返回什么结果 @throws:用于指示一个方法在某些输入的情况下抛出异常或错误 @since:这用于指示该类或函数可用的最早Java版本
举个例子,下面是Javadoc中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比简单的块注释更可取。
Java支持两种类型的注释:
/*多行注释*/:编译器忽略从/*到*/的所有内容。注释可以跨越多行。 编译器会忽略从//到行尾的所有内容。
一些工具(如javadoc)使用特殊的多行注释来实现它们的目的。例如,/** doc注释*/是javadoc在准备自动生成的文档时使用的文档注释,但对于Java来说,它是一个简单的多行注释。
下面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 */
这表示一个文档注释(简称文档注释)。编译器会忽略这种注释,就像它会忽略使用/*和*/的注释一样。JDK javadoc工具在准备自动生成的文档时使用文档注释。
// text
编译器会忽略从//到行尾的所有内容。
现在,关于你应该在什么时候使用它们:
当您想注释一行代码时,请使用// text。
当你想注释多行代码时,使用/* text */。
使用/** documentation */当您想要添加一些关于程序的信息,可以用于自动生成程序文档。
对于Javadoc,首先是在类、接口、方法等的顶部定义。您可以根据名称使用Javadoc来记录您的代码,说明类做了什么或方法做了什么等等,并生成关于它的报告。
第二个是代码块注释。 例如,你有一些代码块,你不想编译器解释,然后你使用代码块注释。
另一个是// 这可以在语句级别上使用,以指定接下来的代码行应该做什么。
还有一些其他的,比如//TODO,这将标记你想要在那个地方做某事
当你有一些临时解决方案,但你想稍后访问并使其更好时,可以使用FIXME。
希望这能有所帮助
对于Java编程语言,两者之间没有区别。Java有两种类型的注释:传统的注释(/*…*/)和行尾注释(//…)。请参阅Java语言规范。因此,对于Java编程语言,/*…*/和/**…*/是传统注释的实例,Java编译器对它们的处理完全相同,即它们被忽略(或者更准确地说:它们被视为空白)。
但是,作为Java程序员,您不仅仅使用Java编译器。你需要使用一个完整的工具链,包括编译器、IDE、构建系统等。其中一些工具的解释与Java编译器不同。特别是/**…*/注释由Javadoc工具解释,该工具包含在Java平台中并生成文档。Javadoc工具将扫描Java源文件并解释/**…*/作为文档。
这类似于FIXME和TODO这样的标签:如果你包含了// TODO: fix This或// FIXME: do that这样的注释,大多数ide都会突出显示这样的注释,这样你就不会忘记它们了。但是对于Java来说,它们只是注释。
请仔细阅读JLS的3.7节,了解Java中注释的所有知识。
有两种评论: /* text */ 传统的注释:从ASCII字符/*到ASCII字符*/的所有文本都会被忽略(就像在C和c++中一样)。 / /文本 行尾注释:从ASCII字符//到行尾的所有文本都会被忽略(就像在c++中一样)。
关于你的问题,
第一个
/**
*
*/
用于声明Javadoc技术。
Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, interfaces, constructors, methods, and fields. You can use a Javadoc doclet to customize Javadoc output. A doclet is a program written with the Doclet API that specifies the content and format of the output to be generated by the tool. You can write a doclet to generate any kind of text file output, such as HTML, SGML, XML, RTF, and MIF. Oracle provides a standard doclet for generating HTML-format API documentation. Doclets can also be used to perform special tasks not related to producing API documentation.
有关Doclet的更多信息,请参阅API。
第二种方法,正如JLS中清楚解释的那样,将忽略/*和*/之间的所有文本,因此用于创建多行注释。
关于Java中的注释,您可能还需要了解其他一些事情
注释不嵌套。 /*和*/在以//开头的注释中没有特殊意义。 //在以/*或/**开头的注释中没有特殊意义。 词法语法意味着注释不会出现在字符字面量(§3.10.4)或字符串字面量(§3.10.5)中。
因此,下面的文本是一个完整的注释:
/* this comment /* // /** ends here: */
我认为现有的答案并没有充分解决这部分问题:
什么时候使用它们?
如果您正在编写一个将在组织内发布或重用的API,那么您应该为每个公共类、方法和字段,以及受保护的方法和非最终类的字段编写全面的Javadoc注释。Javadoc应该涵盖方法签名不能传达的所有内容,比如前置条件、后置条件、有效参数、运行时异常、内部调用等。
如果您正在编写内部API(同一程序的不同部分使用的API),那么Javadoc可以说就不那么重要了。但是为了维护程序员的利益,您仍然应该为任何正确用法或含义不明显的方法或字段编写Javadoc。
Javadoc的“杀手级特性”是它与Eclipse和其他ide紧密集成。开发人员只需要将鼠标指针悬停在标识符上,就可以了解有关该标识符的所有信息。经常参考文档成为有经验的Java开发人员的第二天性,这可以提高他们自己的代码质量。如果您的API没有使用Javadoc进行文档化,有经验的开发人员将不希望使用它。