在 Java 中，注释是代码中的非执行部分，用于向程序添加说明或备注。注释不会被编译器执行，但它们对代码的可读性和维护性非常重要。Java 提供了三种类型的注释：

  1. 单行注释（Single-line comment）
  2. 多行注释（Multi-line comment）
  3. 文档注释（Documentation comment）

1. 单行注释

单行注释用于对一行代码进行简短的说明。它从 // 开始，直到行尾结束。

示例代码：

public class SingleLineComment {
    public static void main(String[] args) {
        int a = 5;  // 这是一个单行注释，说明变量 a 的值是 5
        System.out.println(a);
    }
}

在上面的代码中，// 这是一个单行注释 是对该行代码的简要说明。编译器会忽略该行注释。

2. 多行注释

多行注释可以跨越多行，适用于对较长的代码块或多个语句进行详细说明。它以 /* 开始，并以 */ 结束。

示例代码：

public class MultiLineComment {
    public static void main(String[] args) {
        /* 这是一个多行注释
           可以跨越多行
           适用于对复杂代码块的说明 */
        int b = 10;
        System.out.println(b);
    }
}

在上面的代码中，注释部分跨越了多行。/* 和 */ 之间的内容不会被编译器执行。

3. 文档注释

文档注释是一种特殊类型的注释，用于为类、方法或字段等代码元素生成 API 文档。它以 /** 开始，并以 */ 结束。文档注释通常包含一些额外的信息，如方法的用途、参数、返回值以及异常等。

Java 的文档注释通常与 Javadoc 工具一起使用，Javadoc 工具可以生成基于这些注释的 HTML 文档。

示例代码：

/**
 * 这是一个计算两个数之和的类。
 */
public class Calculator {

    /**
     * 计算两个整数的和
     * @param num1 第一个数字
     * @param num2 第二个数字
     * @return 两个数的和
     */
    public int add(int num1, int num2) {
        return num1 + num2;
    }
    
    public static void main(String[] args) {
        Calculator calc = new Calculator();
        System.out.println("Sum: " + calc.add(5, 3));  // 输出：Sum: 8
    }
}

在这个示例中：

  • 类 Calculator 上的文档注释描述了类的用途。
  • add 方法的文档注释详细描述了方法的功能、参数以及返回值。@param 标签描述了参数，@return 标签描述了返回值。

使用 Javadoc 工具生成文档时，Javadoc 会根据这些注释自动生成 API 文档。

生成 Javadoc 文档的命令：

javadoc Calculator.java

这将根据 Calculator.java 中的文档注释生成 HTML 文件，其中包含类和方法的详细描述。

总结

Java 提供了三种类型的注释：

  1. 单行注释 (//)：用于简短的注释说明，适合单行代码。
  2. 多行注释 (/* ... */)：适用于多行或较长的注释块。
  3. 文档注释 (/** ... */)：用于生成 API 文档，并详细描述类、方法和字段的功能。

合理使用注释可以提高代码的可读性，帮助团队成员更容易理解代码的意图，尤其在团队协作或后期维护时至关重要。