no-comments

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

No comments

不保留注释

Delete comments that describe our own code. Code we own should explain itself through names, types, and structure. Keep a comment only when it documents something outside our control that a reader could not learn from our code.

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

Scope

适用范围

Use the files or diff the user named. Otherwise use the current diff against

main

, including staged, unstaged, and untracked changes:

bash

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

Only touch comments on lines added or modified in scope. Do not sweep untouched code in the same file.

使用用户指定的文件或 diff。否则使用当前分支相对于

main

的 diff，包括已暂存、未暂存和未跟踪的更改：

bash

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

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

Keep

保留

A comment stays only if it is about an external system and is still accurate:

Browser behavior: Chrome/Safari/Firefox quirks, WebCodecs, Canvas, CSS, layout, event ordering, autoplay policy, linked bug trackers.
Media and tooling: FFmpeg, codecs, containers, Mediabunny, Chromium flags, Lambda/Cloud Run limits, Node.js, Bun, TypeScript compiler, bundler behavior.
Third-party libraries and APIs: why we call them in an unusual way, links to upstream issues.
OS, hardware, and spec constraints: file system, GPU, Linux/macOS/Windows differences, RFCs, W3C specs.

Also keep:

Machine-read directives:

eslint-disable*

@ts-expect-error

@ts-ignore

/// <reference>

'use client'

istanbul ignore

prettier-ignore

biome-ignore

@vitest-environment

, shebangs, license headers. Still check that each suppression is needed; remove dead ones.

JSDoc on public exported APIs (it surfaces in editor tooltips).
```
@deprecated
```
tags (see the
```
deprecate-api
```
skill).
Comments in docs, MDX, and code snippets that are shown to users.

只有当注释与外部系统有关且内容仍然准确时，才予以保留：

浏览器行为：Chrome/Safari/Firefox 的异常行为、WebCodecs、Canvas、CSS、布局、事件顺序、自动播放策略以及关联的 bug tracker。
媒体和工具：FFmpeg、codec、容器、Mediabunny、Chromium flags、Lambda/Cloud Run 限制、Node.js、Bun、TypeScript compiler 和 bundler 行为。
第三方库和 API：以非惯用方式调用它们的原因，以及上游 issue 的链接。
操作系统、硬件和规范限制：文件系统、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 和 license header。仍需检查每项抑制配置是否必要；删除已经失效的配置。
公开导出 API 上的 JSDoc（它会显示在编辑器工具提示中）。
```
@deprecated
```
标签（参见
```
deprecate-api
```
skill）。
面向用户展示的 docs、MDX 和代码片段中的注释。

Delete

删除

Narration of what the next lines do (
```
// Get the frame
```
,
```
// Loop over tracks
```
).
Restating names, types, or parameters.
Explanations of our own architecture, data flow, or design choices.
Defenses of workarounds for our own bugs. Fix the root cause in scope or leave the code uncommented.
```
IMPORTANT
```
,
```
do not remove
```
,
```
keep in sync with X
```
,
```
talk to Y first
```
notes about our own code. If the constraint is real, offer to encode it (type, shared constant, test, lint) instead; delete the comment either way.
Commented-out code,
```
TODO
```
/
```
FIXME
```
without a linked issue, changelog-style notes (
```
// Added in v4.0.x
```
), and section dividers.

Mixed comments: keep only the external-system sentence and delete the rest.

If a comment hides a genuine surprise in our code, prefer a clearer name, extracted variable, or type over keeping the comment. Only reshape code when it is a trivial, local change; otherwise delete the comment and mention the surprise in the report.

对后续代码行为的叙述（
```
// Get the frame
```
、
```
// Loop over tracks
```
）。
重复描述名称、类型或参数的内容。
对我们自己的架构、数据流或设计选择的解释。
针对我们自身 bug 的 workaround 辩护。修复范围内的根因，或让代码保持无注释状态。
关于我们自己代码的
```
IMPORTANT
```
、
```
do not remove
```
、
```
keep in sync with X
```
、
```
talk to Y first
```
等说明。如果约束确实存在，应改为提议通过类型、共享常量、测试或 lint 对其进行编码；无论采用哪种方式，都应删除注释。
注释掉的代码、没有关联 issue 的
```
TODO
```
/
```
FIXME
```
、changelog 风格的说明（
```
// Added in v4.0.x
```
）以及章节分隔线。

对于混合注释：仅保留有关外部系统的句子，并删除其余内容。

如果某条注释揭示了我们代码中确实令人意外的行为，应优先使用更清晰的名称、提取出的变量或类型，而不是保留注释。仅在改动简单且局部时调整代码；否则删除注释，并在报告中提及该意外行为。

Steps

步骤

Collect every comment in scope (
```
//
```
,
```
/* */
```
, JSDoc, JSX
```
{/* */}
```
,
```
#
```
in shell/YAML).
Classify each as keep or delete using the rules above. When unsure whether a comment is about an external system, check: would this still be true if we rewrote our code? If yes, keep. If it only makes sense because of how we wrote something, delete.
Delete. Do not change behavior. Remove blank lines left behind that would break formatting.
Run formatting and lint on touched packages:
bash
```
bunx turbo run lint --filter='<package-name>'
```
Report: number of comments deleted, comments kept with a one-line reason each, any constraints offered for encoding, and any code surprises that deserve a follow-up.

收集范围内的所有注释（
```
//
```
、
```
/* */
```
、JSDoc、JSX
```
{/* */}
```
，以及 shell/YAML 中的
```
#
```
）。
根据上述规则将每条注释分类为保留或删除。不确定某条注释是否与外部系统有关时，检查：如果重写我们的代码，这一事实是否仍然成立？如果是，则保留。如果它只有在我们特定的代码实现方式下才有意义，则删除。
执行删除。不得改变行为。移除会破坏格式的遗留空行。
对已触及的 package 运行格式化和 lint：
bash
```
bunx turbo run lint --filter='<package-name>'
```
报告：已删除的注释数量、保留的注释及其各自的一行理由、提议编码的约束，以及值得后续跟进的代码意外行为。