1. 核心原则
- 解释意图，而非翻译代码。注释应说明“为什么这么做”以及“使用时要注意什么”，而不是复述代码的字面动作。
- 注释即代码。修改代码时必须同步更新相关注释，过时的注释比没有注释更有害。
- 能靠命名表达的东西，不要写注释。如
getUserById就不需要注释“通过ID获取用户”。
2. 必须写注释的场景
| 场景 | 要求 |
|---|---|
| 公共函数/接口 | 说明功能、参数约束、返回值含义、异常或错误码 |
| 复杂业务逻辑 | 说明背景、算法来源、产品规则链接，避免后人误改 |
| 临时方案/TODO | 标注 TODO: 说明原因 @负责人 2024-06-01，禁止无头 TODO |
| 非常规写法/踩坑点 | 说明为什么不能按常规方式写，如第三方 SDK 的已知缺陷 |
3. 格式与风格
- 统一采用团队选定的文档规范（如 Javadoc、JSDoc、GoDoc、Python Docstring）。
- 函数/方法注释至少包含：一句话功能描述、参数、返回值、异常/错误（如有）。
- 段落内使用标准标记：
TODO、FIXME、HACK、XXX，保持可检索。
4. 禁止事项
- 禁止注释掉废弃代码。删除它，版本控制会替你保存历史。
- 禁止在注释中泄愤或写猜测。如“这段代码好像有问题”“因为某某乱改导致”。
- 禁止无意义注释。例如
i++ // i 增加 1。
5. 示例
/**
* 计算用户近30天活跃等级。
* 等级规则以产品文档为准：https://wiki.example.com/level-rule
*
* @param userId 用户唯一标识，不允许为 null 或空字符串
* @return 等级编码 1-7；用户不存在时返回 null
* @throws IllegalArgumentException 参数不合法时抛出
*/
public Integer calcUserLevel(String userId) { ... }// 差：未说明业务含义，参数与返回值不清晰
// 计算等级
public Integer calc(String id) { ... }