注释是为了让代码更容易被读懂而附加的描述信息，不参与编译运行，但却非常重要。

　　时刻牢记，代码写出来是为了给人看的。更是为了给三个月后的你自己看的

1.规则

[!concept] concept
Java 的注释主要分为以下三种：

• 单行注释
• 多行注释
• 文档注释

[!pitfall] Warning
注意

1. 多行注释不可嵌套使用
2. 不论是单行还是多行注释，都不参与编译，即编译后的.class 文件中不含注释信息

　　‍

1.1 单行注释

语法

　　// 注释内容

特点

1. 仅作用​当前一行​，// 后面整行都会被编译器忽略；
2. 不能换行，换行后代码恢复执行；
3. 多用于简单临时说明、标记、注释掉单行代码。

示例

int a = 10; // 定义变量a，存储数值10
// int b = 20;  // 注释废弃代码

1.2 多行注释

语法

/*
多行内容1
多行内容2
*/

特点

1. 以 /*​ 开头，*/ 结尾，中间所有内容全部失效，支持跨多行；
2. 不支持嵌套​：/* 外层 /* 内层 */ */​ 会直接报错，内层 */ 提前结束注释；
3. 适用场景：大段代码屏蔽、长段功能说明。

示例

/*
以下代码用于计算两数之和
暂时停用，后续重构
int x = 1;
int y = 2;
*/

1.3 文档注释

语法

　　‍

/**
* 文档注释第一行
* 文档注释第二行
*/

核心区别（和普通多行注释最大差异）

1. 以 /**​ 双斜杠星号开头，普通多行注释是 /*；
2. 可被工具解析生成 API 文档​（Java 的 javadoc 工具、IDEA 自动提示）；
3. 支持专用标签：@param​、@return​、@author​、@version​、@throws 等；
4. 专门用于类、方法、常量的标准化说明，给使用者看接口说明。

示例

/**
 * 计算两个整数相加
 * @param num1 第一个加数
 * @param num2 第二个加数
 * @return 两数相加结果
 */
public int add(int num1, int num2){
    return num1 + num2;
}

　　‍

Javadoc 专用标签

常用基础标签

1. @param 描述方法参数

• 格式：@param 参数名 参数说明
• 适用：有入参的方法

/**
 * 求和
 * @param a 第一个整数
 * @param b 第二个整数
 */
public int sum(int a, int b) {}

2. @return 描述返回值

• 格式：@return 返回值含义
• 适用：有返回值的方法（void 方法不能写）

/**
 * 求和
 * @return 两个数字相加后的结果
 */
public int sum(int a, int b) {}

3. @throws / @exception 抛出异常

　　两者作用一致：说明方法会抛出什么异常、抛出条件

• @throws：推荐使用
• 格式：@throws 异常类名 抛出场景

/**
 * 除法运算
 * @param a 被除数
 * @param b 除数
 * @throws ArithmeticException 当除数b等于0时抛出
 */
public int div(int a, int b) {}

　　‍

类/全局通用标签（写在类上方）

1. @author 作者

　　标注代码编写人

/**
 * 用户工具类
 * @author 张三
 */
public class UserUtil {}

2. @version 版本号

　　标记当前代码版本

/**
 * @version 1.0 2026-07-29 初始版本
 */

3. @since 从哪个版本开始提供该功能

/**
 * @since 1.2
 */

常量/字段标签 @deprecated

　　标记方法/类已过时，不推荐继续使用
搭配 @see 推荐替代方案

/**
 * 旧加法方法
 * @deprecated 已废弃，请使用sum()
 * @see #sum(int,int)
 */
@Deprecated
public int add(int a,int b){}

参考链接标签 @see

　　用于跳转关联类、方法，文档生成后可点击跳转

/**
 * @see User 关联用户实体类
 * @see #div(int,int) 参考除法方法
 */

标签使用规则

1. 必须写在 /** 文档注释 */​ 内部，普通 /* */​、// 无效；
2. 一个标签只能对应一条信息，多个参数要写多个 @param；
3. 标签顺序规范（行业统一）：
   ​@author​ → @version​ → @since​ → @param​ → @return​ → @throws​ → @deprecated​ → @see
4. void 返回值方法不能写 @return​；无参方法不能写 @param。

　　‍

2. 补充使用规范

1. 单行注释优先用 //，简洁轻便；
2. 临时注释掉几十行代码用 /* */；
3. 对外提供调用的类、方法​必须写文档注释；
4. 禁止多行注释嵌套；

　　‍