引言

在 Java 中，注释是非可执行的语句，用于解释代码逻辑、说明设计意图，从而提升代码的可读性。编译器会完全忽略注释，因此它们对程序的运行没有任何影响。注释的主要作用包括：

提升代码可读性与可维护性：清晰的注释帮助其他开发者（或未来的自己）快速理解代码功能和结构
辅助调试与文档编写：在开发过程中，可通过注释临时禁用代码段；同时，注释也是生成 API 文档（如使用 javadoc）的基础，有助于系统化地记录类、方法和参数的用途

三种注释语法

单行注释

单行注释用于对代码中的某一行进行简要说明。在 Java 中，单行注释以 // 开头，编译器会忽略从 // 开始到该行末尾的所有内容

示例：

// 输出 "Hello, World!" 到控制台
System.out.println("Hello, World!");

单行注释常用于：

解释某行代码的作用
临时禁用某行代码（调试时）
添加简短的上下文说明

多行注释

多行注释适用于对复杂的代码逻辑、方法或算法进行详细说明，避免重复使用多个单行注释带来的冗余和不便。在 Java 中，多行注释以 /* 开始，以 */ 结束，中间的所有内容（包括换行）都会被编译器忽略

示例：

/*
 * 该方法计算两个整数的最大公约数（GCD），
 * 使用欧几里得算法实现，时间复杂度为 O(log(min(a, b)))。
 * 输入参数必须为非负整数。
 */
public static int gcd(int a, int b) {
    while (b != 0) {
        int temp = b;
        b = a % b;
        a = temp;
    }
    return a;
}

主要用途：

解释复杂逻辑或算法
注释掉大段代码（如调试时临时禁用多个语句）
提供模块或函数的整体说明

注意：多行注释 不能嵌套（即 /* /* ... */ ... */ 会导致编译错误）

文档注释

文档注释（Documentation Comments）是 Java 中一种特殊的注释形式，专用于生成标准化的外部 API 文档。它们以 /** 开始，以 */ 结束，通常放置在类、接口、方法或字段的声明之前

Java 自带的 Javadoc 工具 可以解析这些注释，并自动生成结构清晰、格式统一的 HTML 格式文档，广泛应用于专业软件开发和开源项目中

主要用途：

描述 类或接口 的功能与设计意图
说明方法的作用、参数、返回值及可能抛出的异常
记录字段或常量的含义
支持团队协作、代码审查和第三方集成

常用 Javadoc 标签：

@param：描述方法参数
@return：说明返回值
@throws 或 @exception：列出可能抛出的异常
@see：提供相关类或方法的引用
@author：标明作者
@version：指定版本信息

示例：

/**
 * 表示一个简单的银行账户。
 * <p>
 * 此类支持存款、取款和余额查询功能，
 * 所有操作均为线程安全。
 *
 * @author Jane Doe
 * @version 1.0
 */
public class BankAccount {

    /**
     * 从账户中提取指定金额。
     *
     * @param amount 要提取的金额，必须为正数
     * @throws IllegalArgumentException 如果金额小于等于零
     * @throws IllegalStateException 如果余额不足
     */
    public void withdraw(double amount) {
        // 方法实现...
    }
}

源本科技 | 码上会

Java 注释

引言

三种注释语法

单行注释

多行注释

文档注释