Java注释是提升可读性、协作与维护的关键，需在类/接口上方说明职责与设计意图，方法前明确输入输出异常，行内注释只解释“为什么”，避免重复、过时或冗余注释。
Java注释不是可有可无的装饰，而是代码可读性、协作效率和后期维护的关键支撑。加在哪儿、怎么加，直接影响别人（包括未来的你）能不能快速看懂逻辑。
类和接口上方：说明整体职责与设计意图
在 public class 或 interface 声明前，用文档注释（/** ... */）描述这个类型是干什么的、解决什么问题、有哪些重要约束或使用前提。不要写“这是一个工具类”这种废话，要具体。
- 比如：/** 用户登录校验器，基于JWT实现无状态鉴权，要求传入非空token且未过期 */
- 避免只写类名重复：“UserManager —— 用户管理类”，这等于没说
- 如果类有典型使用场景，可以加一个简单示例代码块（用 {@code ...} 包裹）
方法定义前：讲清楚输入、输出、异常和副作用
每个 public（以及关键的 protected/package-private）方法都应有文档注释。重点不是“这个方法做什么”，而是“调用它需要什么条件？返回什么？可能抛什么异常？会不会改状态？”
- 用 @param 说明每个参数含义和取值范围（如 “@param timeoutMs 超时毫秒数，必须大于0”）
- 用 @return 明确返回值语义（如 “@return 成功时返回用户ID；失败时返回-1”）
- 用 @throws 列出所有受检异常，以及运行时异常中需要调用方特别注意的（如 NullPointerException 的触发条件）
代码行内或行尾：解释“为什么”，而不是“是什么”
单行注释（//）和多行注释（/* ... */）适合嵌在代码中间，但只用于解释**不直观的决策原因**。如果一行代码本身就能看懂，就别加注释。
立即学习“Java免费学习笔记（深入）”；
- 好例子：// 使用 Math.floorDiv 避免负数除法向零截断（JDK8+）
- 坏例子：// i++ 自增i（纯翻译代码，浪费空间）
- 临时调试用的 // TODO 或 // FIXME 可以保留，但上线前应清理或转为正式任务跟踪
不写注释的地方：比写了错注释更安全
有些位置加注释反而有害。例如：
- private 方法内部细节——除非算法特别复杂或有魔数，否则靠清晰命名+小函数拆分更可靠
- 重复代码块上方——应该重构，而不是注释“这里和上面一样”
- 过时的文档注释（比如方法签名已改但 @param 没更新）——宁可删掉，也别留误导信息
基本上就这些。注释的核心不是“多写”，而是“写对地方、写准原因、写得及时”。代码会变，注释更要跟着动，否则就成了最隐蔽的技术债。
