Java注释的核心是解释“为什么”而非“做什么”，应聚焦反直觉、临时妥协或外部约束的逻辑；Javadoc仅用于public成员并需完整标注@param、@return等；行内注释宜克制，优先重构代码而非添加注释。
Java 注释不是可有可无的装饰，而是代码可维护性的第一道防线。没有注释的代码，哪怕逻辑正确，对他人（或三个月后的自己）来说也接近“黑盒”。
注释的核心作用：解释「为什么」，而非「做什么」
编译器会忽略 //、/* */ 和 /** */，但人不会。真正需要注释的，从来不是显而易见的操作（比如 int count = 0;），而是那些反直觉、绕弯子、临时妥协或依赖外部约束的逻辑。
- 比如循环里跳过某个索引，是因为协议规定该位置保留为未来扩展 —— 这必须用注释说明，否则极易被误删
- 比如某处用了
Thread.sleep(10)而非更精确的等待机制，是因为目标 SDK 版本不支持CountDownLatch—— 不写清楚，后续升级时可能埋下竞态隐患 - 接口返回
null而非空集合，是因为历史兼容性要求 —— 不标注，调用方很可能漏掉判空，触发NullPointerException
Javadoc 注释只用于 public 成员，且必须能生成有效文档
/** */ 不是“高级注释”，它专为 javadoc 工具服务。如果一个 public 方法没配 Javadoc，IDE 通常会警告；但如果写了却漏掉 @param 或 @return，生成的 HTML 文档就会缺失关键契约信息。
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 类注释需说明用途、线程安全性、是否可序列化、典型使用场景
- 方法注释必须覆盖所有
@param、@return、@throws（哪怕只抛IllegalArgumentException） - 避免 “TODO”、“FIXME” 出现在 Javadoc 中 —— 它们属于开发过程标记，不是 API 契约的一部分
- 不要在 private 方法上强行加 Javadoc，除非它承担了关键抽象职责（如模板方法中的钩子）
行内注释和块注释要克制，优先重构而非注释
当发现自己频繁写 // 转成小写再比较，因为数据库字段不区分大小写 这类注释时，往往意味着代码结构出了问题。
- 这类逻辑应该封装成独立方法（如
equalsIgnoreCaseIgnoreCaseInDb()），注释就变成方法名本身 -
/* 如果 status == 2，表示已归档，但前端仍显示为‘处理中’，因 UI 统一状态码映射未更新 */—— 这种注释暴露的是协作断点，应推动同步，而不是长期靠注释“打补丁” - 注释掉的代码（
// int oldId = getId();）必须删除，它既干扰阅读，又制造“这段是不是还有用”的疑虑
最难的不是写注释，而是判断哪一行值得注释。过度注释稀释重点，不足注释掩盖风险。真正有效的注释，永远只出现在设计意图与代码表象不一致的地方。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
