注释

2 阅读2分钟

注释是编程中用来解释代码的作用和功能,以及提供任何重要信息的工具。使用注释能够帮助任何查看代码的人(包括未来的你)更好地理解代码的意图。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" 的例子中,每个注释类型都被用来告知读者代码的某部分功能,或者对整个类的用途做出总结说明。