Java 代码注释规范

问题从哪来

团队里常见的情况是：类能跑、测试能过，但 Javadoc 缺 @param/@return、实体字段没有说明取值约束、枚举值只有字面量没有业务含义。重构或交接时，读者只能反推代码，审查也容易漏掉「字段/枚举必须注释」这类 强制规约。

技能如何约束注释

该技能把注释当成可执行的交付标准，而不是事后补文档。在 新建 Java 类、方法、接口、DTO/Entity、字段、枚举，或修改缺乏注释的复杂逻辑时，要求按层级补齐说明：

• 类：职责、@author、创建日期
• 方法：功能、@param（类型与是否可空）、@return、@throws；构造/重载/接口实现需写清差异或实现要求
• 字段：含义、取值范围、默认值；可用 /** */ 或 JPA @Comment
• 枚举：类级含义 + 每个枚举值的用途与场景；复杂枚举需覆盖多字段逻辑
• 方法内：复杂步骤用 // 断语；算法、TODO（含责任人与时间）、@Deprecated、重大变更单独规范

技能还提供 注释格式表、多套 模板（类/方法/字段/枚举/测试），以及代码审查 检查清单（含「注释与代码一致」「禁止注释掉代码」等）。

适用边界

• 规范以 Java + Javadoc 为主，语言上默认项目级 中文注释（对外 API 可中英双语，术语保留英文如 Redis）。
• 它不会替你写业务设计，只规定「写什么、写在哪、什么格式」；无意义注释（如 i++ 旁写「i 加 1」）和 过时/情绪化注释 属于明确反模式。
• 修改代码时需 同步更新注释；遗留代码应删未用成员，而不是用注释保留旧实现。