java注释应聚焦“为什么”而非“做什么”，需随代码同步更新，确保@param/@return等与实际一致，业务规则须注明依据，todo/fixme要带责任人和截止期，过期未处理应告警。
注释不是写给机器看的，但程序员常当成日志来写
Java 注释本身不参与编译，但写得随意会误导后续维护者。最典型的问题是 @param 和 @return 描述与实际参数/返回值类型或行为不一致，尤其在方法签名重构后忘记同步更新 Javadoc。
- 只对「为什么这么做」写注释，不重复「做了什么」——
if (status == 200)前不用写“判断状态码是否为200”，但可以写“跳过重试逻辑，因 200 表示服务端已成功处理” - 业务规则类注释必须带来源依据，比如：
// 根据《支付接口规范 v3.2》第 4.1 条，超时需返回 ERR_TIMEOUT - 避免在行尾写长注释，特别是含中文时容易破坏对齐；用块注释
/* ... */或独立行注释//更稳妥
IDE 自动生成的 Javadoc 模板别直接交差
IntelliJ 或 Eclipse 按 /** + Enter 生成的模板只是骨架，字段名、类型、返回值都可能和真实实现脱节。更麻烦的是，它默认把泛型擦除后的类型（如 List）当参数类型，而实际可能是 List<order></order>。
- 检查每个
@param是否覆盖了所有形参，特别注意 varargs（String... args）要写成@param args 可变长度字符串数组，至少一个 -
@throws必须精确到具体异常类，不能只写@throws Exception；若方法声明了throws IOException，但实际只抛SocketTimeoutException，就该写后者 - 对重载方法，Javadoc 必须体现差异点，比如：
// 与 overload(String url) 不同，此版本支持自定义超时时间
TODO/FIXME 注释必须带责任人和截止线索
光写 // TODO: 优化缓存策略 等于没写。这类注释在代码里存活超过两周，基本就会被遗忘，反而污染阅读视线。
- 格式统一为：
// FIXME(@zhangsan): 缓存穿透风险，2024-Q3 支付网关升级后移除本地 Map - 禁止出现无上下文的
// HACK或// XXX；如果真需要临时绕过，必须在注释里说明「绕过什么校验」「为什么此时安全」「谁确认过」 - CI 流程中可加检查：扫描源码里未关闭的
FIXME，超期自动发告警到对应人企业微信
注释和代码不同步比没注释还危险
当一段逻辑被重构、分支被合并、或者配置从硬编码改成 yml 后，旧注释还在原地，就成了“精确的错误信息”。比方说，注释写着“使用 RedisTemplate 存储 session”，但实际已切到 RedissonClient，这种错位会让新同学花半小时确认到底该查哪个文档。
立即学习“Java免费学习笔记（深入）”；
- 每次提交前快速扫一遍修改范围内的注释，重点核对：参数名、类名、路径、URL、配置项 key
- 对工具类、DTO、枚举等高频复用代码，把注释检查纳入 PR checklist，而不是靠人工想起来
- 不要依赖 IDE 的「更新 Javadoc」功能——它只改签名，不改语义描述，比如把
userId改成uid后，注释里仍可能留着 “用户 ID 字符串” 而非 “用户唯一标识符”
真正难的从来不是写注释，而是让注释在三个月后依然说得清当时那个 if 分支到底防的是哪种脏数据。
