Java注释的核心是避免误导：单行//仅解释紧邻代码的临时意图或非常规逻辑；多行/.../用于禁用代码或标注边界；Javadoc/*.../仅用于public/protected成员，首句须为完整英文句子。
Java 中注释不是“写不写”的问题，而是“怎么写才不害人害己”的问题——写得模糊、过时或自相矛盾的注释，比不写更危险。
单行注释 // 适合写什么
只用于解释紧邻其下的那行代码的**临时意图**或**非常规逻辑**，比如绕过某个 bug 的补丁、特殊值的业务含义等。它不该重复代码本身已清晰表达的内容。
-
//后面必须加一个空格，再写内容（如// 账户余额不能为负数，而不是//账户余额不能为负数） - 不要用它来“禁用”代码块——那是版本控制该干的事；真要临时屏蔽，请用
/* ... */包裹并加明确标记（如/* DISABLED: legacy retry logic */） - 禁止在方法内部大段堆砌
//来替代重构——如果需要 5 行注释才能看懂 2 行代码，说明这 2 行该拆成小函数
多行注释 /* ... */ 的真实用途
它不是“写长一点的注释”的工具，而是用于：临时注释掉代码、标注代码块边界、或在极少数场景下说明跨多行的约束条件（比如正则表达式或 SQL 拼接）。
- 嵌套不被支持：
/* outer /* inner */ outer end */会编译失败，JDK 不识别嵌套 - 别在 Javadoc 位置误用它——类/方法上方写了
/* ... */，IDE 就不会提取为文档，javac -doc也完全忽略 - 若用来注释掉一段逻辑，请在结尾补上来源提示，例如：
/* REMOVED: replaced by PaymentServiceV2 on 2024-03-15 */
Javadoc 注释 /** ... */ 必须覆盖哪些地方
仅在 public 类、public 方法、public 字段、以及所有 protected 成员上方使用。private 和包级私有成员不需要，写了反而增加维护负担。
立即学习“Java免费学习笔记（深入）”；
- 每个
@param、@return、@throws必须与签名严格一致——参数名拼错、异常类型写错，javadoc工具会静默忽略该标签 - 第一句必须是**完整句子**且以英文句号结尾，这是 IDE 提示摘要的识别依据（如
/** Calculates tax rate based on region. */） - 避免写“本方法用于…”“该字段表示…”——Javadoc 解析器会自动补这些主语，重复写显得冗余
/** * Validates user input before submission. ** Rejects null, empty strings, and strings longer than 50 chars. *
* Note: Does NOT sanitize HTML — caller must handle XSS. * * @param input user-provided string, may be null * @return {@code true} if valid; {@code false} otherwise * @throws IllegalArgumentException if input is longer than 50 chars */ public boolean isValid(String input) { ... }
注释和代码不同步是最常见的“技术债加速器”
没人改注释，因为改了也没报错；但下次有人靠注释理解逻辑再修改代码，就可能引入隐蔽 bug。最有效的防御方式不是“要求大家守规矩”，而是把注释纳入可验证环节：
- CI 流水线中加入
grep -r "// TODO\|// FIXME\|// HACK" src/报警（这些标记必须带责任人和截止日期，如// FIXME(@alice): handle timezone in v2.3） - 对 Javadoc 使用
-Xdoclint:all编译参数，强制检查缺失@param或拼写错误 - 定期用
git log -p -S "//"扫描近期注释变更，确认是否伴随对应代码修改
写注释最难的不是语法，是判断“这里到底值不值得写”。多数时候，删掉一句“显然”的注释，比补上三句“好像有用”的注释，更能提升代码可信度。
