no-comments

不保留注释

删除描述自有代码的注释。我们自己的代码应通过名称、类型和结构来解释自身。只有在注释记录了我们无法控制、且读者无法从代码中了解的内容时，才保留该注释。

范围

使用用户指定的文件或差异。否则，使用当前与 main 的差异，包括已暂存、未暂存和未跟踪的更改：

git diff main...HEAD
git diff HEAD
git ls-files --others --exclude-standard

只处理范围内新增或修改行上的注释。不要顺带清理同一文件中未改动的代码。

保留

只有在注释说明外部系统且仍然准确时，才保留：

• 浏览器行为：Chrome/Safari/Firefox 的特性、WebCodecs、Canvas、CSS、布局、事件顺序、自动播放策略、关联的缺陷跟踪记录。
• 媒体和工具：FFmpeg、编解码器、容器、Mediabunny、Chromium 标志、Lambda/Cloud Run 限制、Node.js、Bun、TypeScript 编译器、打包工具行为。
• 第三方库和 API：说明为何以不寻常的方式调用它们，以及指向上游问题的链接。
• 操作系统、硬件和规范限制：文件系统、GPU、Linux/macOS/Windows 差异、RFC、W3C 规范。

也保留：

• 机器读取的指令：eslint-disable*、@ts-expect-error、@ts-ignore、/// <reference>、'use client'、istanbul ignore、prettier-ignore、biome-ignore、@vitest-environment、shebang、许可证声明。仍需检查每项抑制是否必要；删除已失效的抑制。
• 公共导出 API 上的 JSDoc（它会显示在编辑器工具提示中）。
• @deprecated 标签（参见 deprecate-api 技能）。
• 文档、MDX 和面向用户展示的代码片段中的注释。

删除

• 叙述接下来几行代码的作用（// 获取帧、// 遍历轨道）。
• 重述名称、类型或参数。
• 解释我们自己的架构、数据流或设计选择。
• 为我们自己的缺陷所致的变通方案辩护。在范围内修复根本原因，或不留注释。
• 关于我们自己的代码的 IMPORTANT、do not remove、keep in sync with X、talk to Y first 等备注。如果限制确实存在，应尝试将其编码为类型、共享常量、测试或 lint 规则；无论如何都要删除注释。
• 注释掉的代码、没有关联问题的 TODO/FIXME、类似变更日志的备注（// 于 v4.0.x 添加）以及分节分隔线。

混合注释：仅保留说明外部系统的句子，删除其余内容。

如果注释揭示了代码中真正令人意外的行为，应优先通过更清晰的名称、提取变量或添加类型来表达，而不是保留注释。只有在修改简单且局部时才调整代码；否则删除注释，并在报告中说明该意外之处。

步骤

1. 收集范围内的所有注释（//、/* */、JSDoc、JSX {/* */}、shell/YAML 中的 #）。

2. 根据上述规则将每条注释归类为保留或删除。如不确定注释是否涉及外部系统，请检查：即使我们重写代码，这句话仍然成立吗？如果成立，则保留；如果它只因我们的实现方式才有意义，则删除。

3. 删除注释。不要更改行为。删除后如有空行会破坏格式，请一并移除。

4. 对受影响的包运行格式化和 lint：

   bunx turbo run lint --filter='<package-name>'
   

5. 报告：删除的注释数量、每条保留注释及其一句话理由、建议编码为约束的事项，以及值得后续处理的代码意外之处。