---
id: ka-guidance-注释纪律
kind: guidance
title: 注释纪律
sync_policy: engine_only
status: active
triggers:
  - 写代码
  - 实现
  - 编码
  - 加类
  - 加方法
  - 注释
  - Javadoc
  - 文档注释
extra:
  name: comment-discipline
  scope:
    - '*'
  products:
    - '*'
  category: procedure
  verification_layer: L2
  version: 1.1.0
  last_reviewed: '2026-09-01'
  domain: build
  owner_mechanism: mc-backend-pattern
---

# 注释纪律

> 注释语言和 API 文档格式服从当前项目约定。SoloForge 不强迫英文项目写中文，也不要求每个类和方法都有模板化 doc；目标是保存代码本身无法表达的意图。

## 什么时候需要注释

- 公共 API、扩展点或非显然约束：说明输入、输出、失败语义和兼容承诺。
- 业务不变量、反直觉折中、兼容绕行、性能取舍或安全边界：解释“为什么这样做”和删除条件。
- 临时兼容逻辑：记录触发事实与移除条件（原因写清，不写编号）。

## 什么时候不要注释

- 不复述变量名、控制流或显而易见的实现。
- 不出现任务编号、需求号、工单号、缺陷号等任何形式的过程追踪标记（2026-09-01 收紧拍板：含“仅作外部链接引用”形态；追踪关系由测试名称、测试报告或变更清单承载）。QUAL-COMMENTS 门禁机械拦截。
- 不写“完成某任务”“修复某编号”这类实施流水账，也不写日期+动作的变更日志注释（`// 2026-08-27 by xx 修改`）——修改历史由 git log 承载。QUAL-COMMENTS 门禁机械拦截。
- 不保留过期行为描述；代码变化时同步更新或删除注释。
- 不用大段模板 doc 掩盖职责过多或命名不清。

## 正反例

反例（噪音注释——每条都在增加理解负担）：

```java
public BigDecimal settle(Long orderId) {
    // REQ-014 修改                        ← 任务编号：追踪进测试名称
    // 2026-08-27 by zhang 修复金额计算     ← 变更日志：git log 已承载
    // 调用 settle 方法结算订单              ← 复述代码：删掉零损失
    order.setStatus("SETTLED");            // 设置状态为已结算  ← 复述字面量
    ...
}
```

正例（只留代码本身无法表达的意图）：

```java
public BigDecimal settle(Long orderId) {
    // 结算金额按账单明细重算而非取预缴快照：预缴期间明细可追加减项，
    // 快照会导致少收（不变量：settle 后 bill.locked=1，明细不可再变）。
    ...
}
```

## 自检

- 新读者不查聊天记录也能理解关键不变量和失败语义。
- 注释中的事实、路径和版本仍与当前代码一致。
- 适合由类型、测试或契约表达的内容已经落到可执行载体，而不是只写注释。

## 关联
- [[编码纪律]] / [[证据驱动与反幻觉]]