注释是编程中用来解释代码的作用和功能,以及提供任何重要信息的工具。使用注释能够帮助任何查看代码的人(包括未来的你)更好地理解代码的意图。Java 提供了三种主要类型的注释:单行注释、多行注释以及文档注释(Javadoc 注释)。
下面是一个简单的 Java 程序 "Hello World",其中包含了这三种注释的示例:
/**
* 这是一个文档注释,用于描述 HelloWorld 类。
* HelloWorld 类实现了一个简单的 Java 程序,打印 "Hello, World!" 到控制台。
*/
public class HelloWorld {
/**
* main 方法是程序的入口点,用于执行程序。
* @param args 命令行参数
*/
public static void main(String[] args) {
/* 'println' 方法用于在控制台输出文本
在这里,它将输出 "Hello, World!" */
System.out.println("Hello, World!"); // 打印 "Hello, World!" 到控制台
}
}
单行注释
单行注释以双斜线 //
开头,持续到行末。它们通常用于简短的描述或解释紧随其后的代码:
// 打印 "Hello, World!" 到控制台
System.out.println("Hello, World!");
或
System.out.println("Hello, World!"); // 打印 "Hello, World!" 到控制台
多行注释
多行注释以 /*
开头,以 */
结束。它们可以跨越多行,因此适合注释掉一大块代码,或者对接下来的一段代码进行详细说明:
/* 'println' 方法用于在控制台输出文本
在这里,它将输出 "Hello, World!" */
System.out.println("Hello, World!");
文档注释(Javadoc)
文档注释是由一对 /**
和 */
包围的多行注释,它们通常用于描述所注释的结构(类、方法、字段等)。JDK 的 Javadoc 工具使用这些注释来生成文档,有关Javadoc
的详细信息,请参阅 Javadoc™ 文档:
/**
* main 方法是程序的入口点,用于执行程序。
* @param args 命令行参数
*/
这些注释中可以包含 Javadoc 标签来提供额外的信息,例如 @param
用于描述方法参数,@return
用于描述返回值等。这些文档注释不仅用于生成 API 文档,也可以通过 IDE 在编码时提供即时的帮助和说明。
在实际编码实践中,注释应该清晰而富有信息量,尽可能提供有价值的指导,同时避免无谓或者太过显而易见的评论,因为过度注释可能会分散对代码本身的关注。在 "Hello World" 的例子中,每个注释类型都被用来告知读者代码的某部分功能,或者对整个类的用途做出总结说明。