注释里别写可 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/ 下临时建文件,注释里写它们的模式):
scan:nested-scroll --strict 与 scan:count-window --strict 均 0 命中。
原因:它们检测的是组合形态(例如 DataGrid 容器 + overflow 的共现), 单独一个字面量出现在注释里不构成命中。 ⇒ 「裸扫」不等于「会被注释污染」,取决于 pattern 有多具体。
🔴 这条订正本身就是个教训:上一版我在治「未经验证的断言」的同一份文档里, 写下了一条未经验证的断言。列表里每写一个 ❌ 都该有一次实测。
⇒ 仍要问「这串字符会不会有人拿去 grep」的,现在主要是手写的一次性 grep -c。
触发场景¶
写「这里为什么要有 X」的解释性注释时,很自然会把 X 原样写进注释:
⇒ 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 不脏。