diff --git a/docs/DEV-TOOLING.md b/docs/DEV-TOOLING.md index 58de210..55f4cc5 100644 --- a/docs/DEV-TOOLING.md +++ b/docs/DEV-TOOLING.md @@ -184,7 +184,24 @@ bash deploy/prune-deploy-artifacts.sh --self-check # 判据自检(16 项, 9. **变异之前先提交。** 我在**未提交**状态下变异,然后用 `git checkout HEAD -- ` 还原,把自己的改动一起冲掉了(这条纪律我写过、还是踩了)。 顺序必须是:提交 → 变异 → 确认红 → `cp` 还原 → `cmp` 校验。 -10. **注释里的数字无法被判据守住。** 同一文件里曾同时写"写点五处"和"共 6 处" +10. **改"布局/文件集"时,先在脑子里跑一遍"如果这一步被回滚,部署判据会怎么变"。** + (pi 2026-09-14 提的,很准。)实例:把 `lib/user-question.js` 搬到 `test/lib/`, + 收益是"快照更干净";但**回滚它会让快照立刻多出一处运行时漂移** —— + 因为快照是"搬家后"的树,而仓库回到了"搬家前"。这类改动的收益账里没有这一项, + 于是它不体现在任何判据里,只体现在回滚之后的红灯上。 +11. **判据的退出码不许经管道取值**(与第 6 条同源,写清取法):临时命令里 + `cmd | tail -25; echo $?` 拿到的是 `tail` 的退出码。**要取就读 `${PIPESTATUS[0]}`**。 + 脚本侧四个 deploy 脚本都有 `set -o pipefail`(`install.sh` 还带 `-e`), + 所以脚本内的管道判定是对的 —— **但那是判据的一部分,不是风格**: + `redeploy-plugin.sh` 的 `if ! node … | sed …; then` 与 `install.sh` 里同形状那处, + 依赖 `pipefail` 才测的是被检程序的状态;谁重构时把 `set -o pipefail` 删了或挪了位置, + 判定会静默变成"`sed` 成功即成功"。**动那几行要连着 pipefail 一起想。** +12. **判据的输出必须能自证"它比完了全部对象"。** 实例:`check-shared-libs.sh` 的 + `show_diff` 里 `cmp … | head -3` 在 `set -euo pipefail` 下返回 1 ⇒ 独立调用触发 + `set -e` ⇒ **脚本当场中止**:只报第一个分叉文件,后续对象与收尾汇总都不打印。 + 退出码**恰好还是 1**(判定是对的),所以光量退出码看不见它 —— + 这正是"判定对、证据被截断"。修法 `|| true`,并在注释里写明它不是风格而是判据。 +13. **注释里的数字无法被判据守住。** 同一文件里曾同时写"写点五处"和"共 6 处" (且它的式子 2+2+3 加起来是 7,实际 10 处)——**三处说法三个数**。 与"不要手抄期望用例数常量"同源:**两组矛盾的数字比没有数字更糟**, 因为它让读者以为有人数过。要判覆盖完整只能靠**机制**(整段 try/catch),不靠数数。