Java注释分三种：单行（//）、多行（/.../）、文档（/*.../）；分别用于行级说明、块级禁用、API文档生成，核心是提升可读性与协作性，且需随代码同步更新。
Java 中的注释共三种：单行注释、多行注释、文档注释。它们用途不同，语法不同，编译器处理方式也不同——但核心目标一致：让代码更易读、可维护、可协作。
单行注释（//）适合快速说明和临时禁用
以 // 开头，作用范围仅限当前行末尾。常用于：
- 解释某一行变量或逻辑的意图，比如
int timeout = 3000; // 单位毫秒，超时阈值 - 临时屏蔽一行代码调试，如
// System.out.println("debug: " + value); - 标记待办事项，配合
TODO、FIXME等关键词，例如// TODO: 后续支持异步回调
注意：不要堆叠多行 // 来模拟多行注释；也不要用它重复代码已明确表达的动作（如 i++; // i加1）。
多行注释（/* ... */）用于块级说明或临时停用代码段
以 /* 开始、*/ 结束，中间内容完全被忽略。适用于：
- 对几行相关代码做整体说明，比如算法步骤、业务规则限制
- 临时注释掉一段暂时不用但可能恢复的代码（比删掉更安全）
- 在调试中批量禁用逻辑分支，例如整个 if 块
关键限制：不能嵌套使用，即 /* 外层 /* 内层 */ 外层 */ 是非法的；但内部可以包含 //，不影响语法解析。
文档注释（/** ... */）是生成 API 文档的唯一标准形式
以 /** 开始、*/ 结束，必须紧贴在类、接口、方法、字段等成员声明之前。它的价值在于可被 javadoc 工具提取并生成 HTML 文档。
合格的文档注释应包含：
- 首句用动词开头，概括功能（如 “验证用户邮箱格式是否合法”）
- 使用标准标签说明关键信息：
@param描述参数含义与约束，@return说明返回值语义，@throws列出可能异常及触发条件 - 避免空泛描述，聚焦“为什么这么设计”或“调用者需注意什么”
示例：
// 正确写法/** * 根据手机号查询用户基本信息，不包含敏感字段。 * @param phone 手机号，11位数字字符串，不能为空 * @return 用户对象；若未找到或格式非法，返回 null * @throws IllegalArgumentException 当 phone 含非数字字符时抛出 */public User findUserByPhone(String phone) { ... }
注释不是装饰，而是沟通契约
真正有用的注释回答的是“为什么”，而不是“做什么”。代码本身应尽量自解释（靠命名、结构、拆分），注释则补足那些无法从语法直接看出的信息：
- 隐藏的约束（如“此方法线程不安全，调用方需自行同步”）
- 权衡取舍（如“此处用 HashMap 而非 TreeMap，因无需排序且读多写少”）
- 外部依赖（如“该时间戳来自 NTP 服务器，误差控制在 ±50ms 内”）
一旦代码修改，对应注释必须同步更新；过期注释比没有更危险。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
