跳转至

注释里别写可 grep 的代码字面量

一句话

本仓有大量判据靠 grep -c 数命中(scan-issue-coverage 的 41 个 audit_grep pattern、 每个 issue 的回归判据、pnpm verify 的多个扫描器)。 在注释里写出与代码相同的字面量,会让这些判据多数一处,从而判错。

🟢 2026-09-19 更新:audit_grep 这一类已经有机器解法

scan:issue-coverage 的 audit_grep 条目现在支持 scope: "code" —— 匹配前先剥掉 JS/TS 文件的注释。写这类判据时直接加上它, 注释就可以把「为什么禁这个写法」写准确了:

audit_grep:
  - pattern: "width: 260"
    description: "两个写死的 260px 吃掉整行 68%,写回来就是复发"
    expect: absent
    scope: "code"          # ← 注释里怎么提都不算违规
    paths: "src/sections/task/task-view.tsx"

⚠️ 但它只覆盖 audit_grep 一种

下面这些仍然会被注释污染,本文其余部分对它们原样有效:

判据形态 是否已解决
ISSUE frontmatter 的 audit_grep ✅ 加 scope: "code"
tests/*.test.ts 里的源码断言 ✅ 用 tests/_helpers/code-only.ts
scan:count-window / scan:nested-scroll 等专项扫描器 🟢 实测不受影响(见下)
scan:error-handling 🟢 基线模式,误报会被基线吸收
手写的 grep -c 'xxx' src/... 一次性核查 ❌ 仍是裸 grep

🟢 2026-09-19 实测订正:专项扫描器不受注释污染

本文上一版把这几个扫描器一律写成「❌ 仍是裸扫」—— 那是推断,没有验证过。 实测(在 src/ 下临时建文件,注释里写它们的模式):

// 这行注释里写 overflow: 'auto' 只是为了解释为什么禁它
/* 块注释里也提到 overflowY: 'scroll' */

scan:nested-scroll --strict 与 scan:count-window --strict 均 0 命中。

原因:它们检测的是组合形态(例如 DataGrid 容器 + overflow 的共现), 单独一个字面量出现在注释里不构成命中。 ⇒ 「裸扫」不等于「会被注释污染」,取决于 pattern 有多具体。

🔴 这条订正本身就是个教训:上一版我在治「未经验证的断言」的同一份文档里, 写下了一条未经验证的断言。列表里每写一个 ❌ 都该有一次实测。

⇒ 仍要问「这串字符会不会有人拿去 grep」的,现在主要是手写的一次性 grep -c。

触发场景

写「这里为什么要有 X」的解释性注释时,很自然会把 X 原样写进注释:

// ISSUE-0091:sync: 0 不能省 —— 本行可能被旧云通道取走
const updateFields: any = { scrape_status: 2, sync: 0 };

⇒ grep -c 'sync: 0' 得 2,而实际代码只有 1 处。

判据

写注释时问一句:这串字符会不会有人拿去 grep?

会被 grep 的典型: - 函数名、消息类型名('open-page-settings') - 字段赋值(sync: 0、scrape_status: 2) - 调用形态(openWindow('results')) - 任何出现在某个 issue「回归判据」代码块里的串

怎么写

别写 改写成
// sync: 0 不能省 // 同步标志必须重置
// 全仓 grep openWindow('results') 零命中 // 全仓只有 main / settings / login 被真实调用
// grep 'open-page-settings' 只有此处 // 全仓除本行外无第二处出现该消息名

要点:用自然语言描述那个东西,不要复制它的字面形态。 确实必须写出字面量时(例如给后人指路),在同一行注明 // 注:此处刻意不写完整串,避免污染 audit_grep,或把字面量拆开写。

实证(2026-08-31 一天两次)

# 场景 后果
1 ISSUE-0093 标注里写了 openWindow('results') 与 'open-page-settings' 自测时 grep 命中数被自己的注释污染,差点据此判「有调用方」
2 ISSUE-0091 修复注释里写了 sync: 0 grep -c 得 5,与 issue 记载的 4 处终态点对不上,多花一轮排查

两次都是先写注释、后跑判据才发现。第二次是在第一次刚改完的同一小时内犯的 —— 说明光知道这条不够,要在写注释的当下就想到。

实证续(2026-09-19,又是一天两次)

# 场景 后果
3 ISSUE-0177 的 width: 260(absent)命中 task-view.tsx 两处注释 commit 被闸拦下,只能改软措辞:「原来这一栏写死 260px」——解释力下降
4 ISSUE-0178 的 location.reload(absent)命中 guard 文件头注释 同上,刚在上一条的 commit message 里记完教训,同一天转头又犯

🔴 这两次暴露的是:光把教训写进 commit message / 规则文档不管用 (文档是读了才生效,闸是跑了就生效)。 而且这条规则要求的是「每次写注释都要想起它」—— 一条需要人持续保持警觉的规则,本身就是不稳的。

⇒ 所以当天做了 scope: "code",把 audit_grep 这一类从规则变成机制。 两处被改软的注释措辞随之改了回去。

反向提醒

这条不是让你少写注释。解释「为什么」的注释仍然要写足, 只是把形态换成自然语言。信息量不减,grep 不脏。