java注释应服务于可读性与协作，单行注释//用于局部逻辑说明，多行注释/.../用于临时屏蔽代码，文档注释/*.../专用于生成api文档，三者不可混用。
写好注释不是为了应付检查，而是让代码更易读、易维护、易协作。Java 提供三种注释方式，每种有明确用途，混用或滥用反而降低可读性。
单行注释 //：解释局部逻辑，别写废话
单行注释适合说明某一行或相邻几行的意图，尤其是不直观的操作。它紧跟代码之后或独占一行，但不要用来描述显而易见的内容（比如 int i = 0; // 初始化i 就多余）。
- 用在变量声明后，说明其业务含义：// 用户登录失败次数，超过3次锁定账号
- 用在条件判断旁，解释特殊判断依据：// 避免浮点数直接比较，用误差范围
- 临时禁用某行代码调试时可用，但提交前应清理
多行注释 /* ... */：标记废弃代码或临时屏蔽大段逻辑
多行注释适合包裹几行到十几行的代码块，常用于临时调试、注释掉旧实现，或写简短的模块说明。但它不能嵌套，也不该用来写函数说明——那是文档注释的事。
- 调试时可包裹一段逻辑：/* if (debugMode) { log.info("进入校验流程"); } */
- 替换旧算法时保留原代码作参考：/* 旧版校验逻辑（兼容v1协议） ... */
- 避免在方法内部用它写长说明——会干扰代码结构，也难被IDE识别
文档注释 /** ... */：为public类、方法、字段生成API文档
只有以 /** 开头的注释才会被 javadoc 工具提取生成HTML文档。它必须紧贴被注释元素上方，且需遵循标准标签语法。
- 类注释写清用途和设计意图：/** 用户管理服务，基于JWT实现无状态鉴权 */
- 方法注释包含 @param、@return、@throws：/** @param userId 用户唯一标识 @return 用户完整信息，可能为null */
- public 字段建议也加文档注释，说明其语义与约束（如是否可为空、单位、取值范围）
- private 方法一般不用文档注释，除非是关键工具方法且会被其他模块间接调用
三个容易踩的坑
规范不是教条，但绕开常见错误能省下大量沟通成本：
- 别用文档注释写“TODO”或“FIXME”——这些用单行注释 + IDE 能识别的标记更合适
- 别在文档注释里写实现细节（比如“这里用了HashMap，因为O(1)查表”），专注“做什么”和“怎么用”
- 团队内统一注释风格（如是否空行、缩进、标点），用 Checkstyle 或 SpotBugs 可自动检查
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
