code-comments

代码注释

删除所有不在保留清单中的注释。如果不确定某条注释是否符合某个条目，就删除它。解释我们自己代码的注释通常意味着代码应该修改：让代码本身表达清楚，然后删除注释。编写代码时要添加注释，先按同一份清单审视它。

保留清单

只有符合以下某个条目的注释才予以保留，并且仅在其所述内容当下仍然成立时保留：

1. 法律或许可证声明。
2. 工具指令，例如 // prettier-ignore、 @vitest-environment 或编译器 pragma。Lint 和类型检查抑制还必须符合抑制规则。
3. 供模块外部使用的 API 文档注释，用于说明签名和类型无法表达的内容：单位、所有权、副作用、抛出的错误、拒绝的输入。
4. 代码之外设定的约束：依赖项或平台的 Bug、供应商或协议规则、业务规则、法规。注释应注明来源；如果存在相关 issue、规范、RFC 或 ADR，还应链接过去。变通方案还应说明移除该方案的条件。
5. 代码暂时无法表达的、对我们自身代码的真实约束，例如必须遵守的调用顺序，或看似可以删除但实际不可删除的代码行。只有在代码修改、类型、断言或测试消除这一需求之前，才予以保留（步骤 2 和 4）。
6. 链接到已跟踪 issue 的 TODO。

审查每条注释

按以下步骤依次审查范围内的每条注释。

1. 核实其内容。 阅读代码及其调用方。删除内容错误或已过时的注释。IMPORTANT、NOTE、do not remove、careful、for now，以及超过两行的任何理由，都是需要核实的说法，而非保留注释的理由。
2. 让代码本身表达清楚。 如果注释解释的是我们自己的代码，就修改代码，让注释变得多余，然后删除注释。在清理或审查中，只做不改变行为的修改：确认使用方后重命名，或提取具名常量或局部变量。对于会改变函数（即使是私有函数）行为或参数的修改，应另行准确报告符号名称和修改内容。此时，注释进入步骤 3；在修改完成前，它通常符合条目 5。
3. 对照保留清单。 保留符合某个条目的注释。逐句判断：删除不符合该条目要求或无法核实的句子，不要改写其余内容。
4. 为每条条目 5 的注释提供编码方案：类型、断言或测试，确保有人违反约束时会失败。只有获得用户批准后才添加，然后删除注释。
5. 删除其余注释。 将仍有价值的内容移至恰当的位置：
   • 任务历史（修改了什么、由谁批准、尝试过什么、如何验证）放入提交说明或 PR。
   • 没有关联 issue 的 TODO 放入报告，供后续创建 issue。
   • 从常量复制而来的值改为引用该常量。
   • 已注释掉的代码、文件头、分节横幅和“Used by”列表直接删除，不作替代。Git 历史和搜索就能回答相关问题。

抑制规则

eslint-disable、@ts-ignore、@ts-expect-error、# type: ignore、# noqa、swiftlint:disable、//nolint 和 #[allow(...)] 会关闭某项检查。判断之前，先查明对应规则会检查什么。

• 规则仅涉及代码风格，或在此处不适用：保留抑制。如果原因不明显，用几句话说明该规则在此处为何不适用。
• 规则能捕获 Bug，例如类型错误或不安全代码：抑制会掩盖缺陷。如果待审查的修改新增了该抑制，就修复代码并删除抑制；否则报告符号名称和规则。

清理或审查更改

1. 确定范围。 默认使用更改新增或编辑的注释：与基准分支的差异，包括尚未提交的工作。用户指定文件时，使用这些文件。其他注释一律不要动。
2. 本次会话编写的代码，交由新的读者审查。 你记得每条注释为何而写。下一位读者不会记得，没有共享上下文的子 Agent 也不会，所以它会像那位读者一样判断。把此文件的路径和审查范围告诉它。要求它只编辑注释，并报告建议的代码更改、编码方案和抑制项。没有子 Agent 工具时，自己执行审查。
3. 按上述标准判断每条注释。
4. 审计子 Agent 的工作（如果运行了审查）。只有当删除的注释按原样符合保留清单中的某一项时，才恢复该注释。撤销所有注释以外的更改。
5. 撰写报告，以删除的注释数量开头。然后列出每条保留的注释及其对应的保留清单项、已做或建议的每项代码更改及其符号、编码方案、报告的抑制项，以及删除但未关联问题的 TODO。

当代码属于他人（例如队友的 PR）时，报告审查发现，不要编辑。

形式

对于保留的注释：

• 一到两行。只有在说明约束确有需要时才写得更长。
• 使用通俗词语和领域自身的名称。
• 每项陈述都必须基于代码、经验证的行为或维护中的来源。不要凭记忆写性能数字。
• 精确说明运行时不变量。
• 对于变通方案，按执行顺序解释其机制，并说明仍然存在的限制。
• Lint 和兼容性选择属于权衡。说明牺牲了什么，不要说这是规则。

示例

保留。该约束由我们的代码之外设定：

// The payments provider retries a webhook until it gets a 2xx response,
// so the same event can arrive more than once.
if (await processedEvents.has(event.id)) return ok();

让代码表达清楚。该注释解释的是我们自己的命名：

# t is the timeout in milliseconds
def connect(host, t): ...

变为

def connect(host, timeout_ms): ...

提出编码方案。调用顺序是我们自己代码中的真实约束：

// Must run before initAnalytics(), which reads the consent flag.
loadConsent();
initAnalytics();

传入该值后，调用顺序便不可能被破坏： initAnalytics(loadConsent())。在用户批准该更改之前，保留这条注释。

删除。该警告已过时：

// IMPORTANT: do not remove. The dashboard reads this field.
user.legacyId = user.id;

搜索后发现没有任何地方读取 legacyId。删除该注释，并报告这个无用赋值。