注释：三条判据 + 四分类

大段的注释是负资产。它和代码各自维护，却没有任何编译器替你发现两者分叉；而读者会相信它。一句错的注释比没有注释贵得多——它把后来的人指向错误的方向，而且不会红。

所以默认少写：只有代码表达不了的东西才写。

三条判据

写之前问，评审时也问；三条同时满足才留。

规模上限：一块注释最多 3 条可独立核实的断言；@file 头一行（文件名 + 一句话职责）。清单式内容（模式表、字段表）按「一行一条」计，散文段落零容忍。

载体：能降级就降级

同一件事有四种可放的地方，越靠前越不容易烂：

所以处置顺序是往下压：能写成测试的先写测试，能让命名自解释的先改名，剩下的才写注释。注释是这套体系里唯一「错了也没有探测器」的载体，这正是它必须短、必须只讲不会随实现变化的断言的原因——它的唯一价值是挡住后人把正确的代码改错（Chesterton 的栅栏），不是替人解释代码。

指针不是免罪符：// 见 docs/xxx §3 把读者送到另一个同样没有探测器的地方，还把一次跳转的成本加在他身上。除非那份文档与代码同仓、改动这个函数时一定会改那一节，否则不写指针；指向按日期冻结的产物（某次基线的快照）尤其没有意义——它本来就不会再更新。

四分类

B 类的产物通常既不是文档也不是长注释，而是一条测试或一个更好的名字；只有「同一份推导要跨多个文件共享」时才进设计文档，且那一节必须与代码同批维护。

D 类判定（2026-10-23 实证污染）

代码注释里出现以下即 D 类，删除：

• "XX 产物不入 git / 留本地 / QA 取阅 / 移出版本库 / 加忽略 / 工作区不再变脏"——.gitignore 就是声明地，注释冗余
• "（J-47 纪律）（J-50 同构形态；查询口本批不落，显式挂账）"——台账编号无背景 = 黑话；纪律事实在评审文档/设计文档
• "跑完门禁工作区不再变脏"——协作黑话
• 内部编号（I-xxx / EP-xx / DV-xx / R-xx）——编号的宿主是台账和卡片，项目收尾会归档或删；代码里的编号比文档活得久，最终一定指向一个不存在的条目
• 处置对照：A 保留 / B 迁移设计文档 / C 删除 / D 删除（治理事实补 .gitignore 或脚本头部一句话，不写编号）

强制保留面（A 类）

• 版权/许可头（法律要求，非解释性注释）
• 公共 API 契约标注（与项目自身审核必检清单绑定，删了会被打回）
• 默认值的推导依据（容量链/对齐关系，防后人改错无据）
• 行为契约（回调/异常语义，是测试判据来源）

迁移与删除的顺序（Chesterton's Fence）

1. 先核实：这块注释现在还是真的吗？按三条判据回源核一遍——错的直接删，不要搬进文档，否则只是把负资产挪了个地方。
2. 再补测：删除"看似冗余"的校验/逻辑前，确认测试已锁定该行为；未锁定先补测试。
3. 后降级：真的那部分先试测试、再试命名，都装不下才写成 1–3 条断言留在代码里；文档是最后手段，不是默认落点。

存量清理的时机

新写的按本策略，存量不逐卡顺手改：一张卡顺手清一个文件，评审面被摊大、还容易把没测住的行为一起删掉。放到项目收尾做一次全仓扫描，逐块按三判据判一次——有测试锁住行为的直接删，没有的先补测试，补不动再压到 3 行内。

比例这件事也只有全仓一起看才成立：一个 40 行的类挂 30 行散文，功能代码被注释淹掉，单看某个块每块都"不算长"。边写边清只会得到"新的干净、旧的照旧"。

复述删除（C 类）

• 与头文件契约重复的实现注释
• 用例名已自注释的体内注释
• 防御注释（代码本身 if 判空已自明）
• enum 值旁"合法/非法"等自明注释

代码自注释配套

改名让结构自注释（名实相符、成员惯例统一、类型即文档），与注释删除是配套动作，不是先删再猜。

边界

• "全删"不采纳：契约面与项目自身规范冲突（审核必检清单强制项）。
• 结构化格式（对齐全矩阵、协议字段表）同样受 3 条上限约束；表本身进文档，代码留键名。
• 结构自注释可选项（如所有权型 unique_ptr 替代 bool）记录不强制，按简单优先。