Java注释只有三种：//、/.../、/.../，各自有严格使用场景。//仅用于单行临时意图或禁用代码；/.../仅用于临时屏蔽代码块，禁用嵌套；/.../必须置于声明正上方，遵守@param/@return等标签规则，且须与代码同步更新，否则导致工具链失效。
Java 注释只有三种，但用错地方会直接让团队协作变卡顿，尤其 Javadoc。
单行注释 // 什么时候该用、什么时候不该用
它只该出现在「解释某一行代码的临时意图」或「临时禁用某行」，不是写说明文档的地方。
- 适合：快速标注调试逻辑，比如
// 这里暂不校验空值，后续补 - 不适合：描述方法功能、参数含义——这种信息不会被 IDE 提取，也不进文档生成流程
- 常见错误：用
//写长段落说明，结果别人改代码时漏看，以为那段逻辑已废弃 - 性能无影响，但过度使用会让代码视觉噪音变大，IDE 折叠时还藏不住
多行注释 /* ... */ 的真实使用场景和陷阱
它不是「写大段说明」的替代品，而是用来临时屏蔽代码块，或在极少数需要跨行写「非结构化说明」时才用。
- 适合：批量注释掉一段测试代码，比如
/* System.out.println(x); doSomething(); */ - 不适合：嵌套使用——
/* outer /* inner */ outer end */会编译失败，Java 不支持嵌套 - 注意：
/*开头后如果紧跟着*（即/**），会被 IDE 当作 Javadoc 起始，可能触发错误提示 - 兼容性没问题，但 Git 差异对比时，整块被注释掉的代码会丢失上下文，不如用
//逐行关更清晰
Javadoc 注释 /** ... */ 必须遵守的硬规则
它不是可选装饰，是 Java 生态里 API 可发现性的基础设施——IDE 补全、Maven site 文档、Spring Boot Actuator 的 endpoint 描述都依赖它。
立即学习“Java免费学习笔记（深入）”；
- 必须放在类、接口、方法、字段声明的正上方，且只能有一个
/**块 - 核心标签不能乱用：
@param只能用于有参方法，@return只能用于非void方法，@throws后必须跟真实声明的异常类型 - 常见错误：
@param userId却没在方法签名里定义userId变量；或写@return the result，而实际返回的是Optional<String>，IDE 会标黄警告 - 生成文档时，
{@code System.out.println()}用于内联代码，{@link #methodName()}才能正确跳转，写成@see methodName()就只是纯文本
注释和代码不同步才是最大技术债
比语法错误更危险的是过期注释——它会让人误信错误的前提，尤其 Javadoc 里写的「此方法线程安全」，实际早已加了静态锁却忘了更新。
- 修改方法逻辑后，第一件事不是测功能，是扫一眼对应的
@param和@return是否还准确 - CI 流程里可以加
mvn javadoc:javadoc -DfailOnError=true，让 Javadoc 解析失败直接中断构建 - IDEA 默认不检查
@param名称是否匹配参数名，要手动开 Settings → Editor → Inspections → Java → JavaDoc →Missing @param和Invalid @param
很多人以为注释是写给人看的，其实它首先是写给工具链看的。一旦格式或语义错位，IDE 补全失效、文档生成空白、甚至 SpringDoc 里接口描述变成“null”，问题就藏得特别深。
