Java 代码注释

注释是程序中不会被编译器执行的部分，它们的存在是为了向人类读者解释代码的功能、目的或复杂逻辑。编写良好、清晰的注释是专业软件开发的重要实践之一。Java 支持三种类型的注释。

1. 单行注释 (Single-line Comment)

单行注释以双斜杠 // 开始，直到该行的末尾结束。它通常用于对单条语句或一小段代码进行简短的解释。

语法:

// 这是一个单行注释

示例:

int age = 30; // 声明并初始化一个名为 age 的变量

// 调用方法来计算总和
calculateSum();

2. 多行注释 (Multi-line Comment)

多行注释以 /* 开始，以 */ 结束。可以跨越多行，通常用于提供更详细的解释，或者临时禁用一大段代码。

语法:

/*
  这是一个多行注释。
  它可以包含任意数量的文本行。
*/

示例:

/*
 * 这是一个计算两个整数之和的方法。
 * 参数 a: 第一个整数
 * 参数 b: 第二个整数
 * 返回值: a 和 b 的和
 */
public int add(int a, int b) {
    return a + b;
}

/*
  暂时禁用以下代码块进行测试
  String message = "Hello";
  System.out.println(message);
*/

注意: 多行注释不能嵌套。例如，/* ... /* ... */ ... */ 是无效的。

3. 文档注释 (Documentation Comment)

文档注释是一种特殊的多行注释，它以 /** 开始，以 */ 结束。这种注释可以被 javadoc 工具提取，自动生成程序的官方 API 文档。

文档注释是为类、接口、方法和字段提供专业、标准化描述的最佳方式。它支持使用特殊的 @ 标签来标记参数、返回值、异常等信息。

语法:

/**
 * 这是一个文档注释。
 * @tag 描述
 */

常用 Javadoc 标签:

• @param: 描述方法的参数。
• @return: 描述方法的返回值。
• @throws 或 @exception: 描述方法可能抛出的异常。
• @author: 标明作者。
• @version: 标明版本号。
• @see: 引用其他相关的类或方法。
• @deprecated: 标记一个方法或类已过时，不推荐使用。

示例:

/**
 * 代表一个银行账户，提供存款和取款功能。
 * 
 * @author Cascade
 * @version 1.0
 */
public class BankAccount {

    private double balance;

    /**
     * 向账户中存款。
     * 金额必须是正数。
     * 
     * @param amount 要存入的金额，必须大于 0。
     * @throws IllegalArgumentException 如果存款金额为非正数。
     */
    public void deposit(double amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException("存款金额必须为正数");
        }
        this.balance += amount;
    }

    /**
     * 获取当前账户余额。
     * 
     * @return 账户的当前余额。
     */
    public double getBalance() {
        return this.balance;
    }
}

为什么以及何时写注释？

• “为什么”而不是“是什么”: 好的注释应该解释代码的意图（为什么这么做），而不是简单地复述代码本身（代码在做什么）。

  • 不好的注释: i++; // 将 i 的值加 1 (这是显而易见的)
  • 好的注释: i++; // 索引需要跳过标题行 (解释了原因)

• 复杂逻辑: 当您编写了一段复杂的算法或业务逻辑时，添加注释来解释其工作原理。

• 公共 API: 所有公开给其他开发者使用的类和方法都应该有详细的文档注释。

• 代码维护: 当您修复一个 bug 或进行一个不直观的修改时，留下注释说明原因。

记住，代码本身应该是清晰和自解释的。注释是补充，而不是用来补救写得糟糕的代码。整洁的代码加上恰到好处的注释，才是高质量软件的标志。