Back to Details

verifying-before-done

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Verifying before done

完成前的验证

REQUIRED BACKGROUND: the 
principal-engineering
skill.
必备背景知识： 
principal-engineering
skill.

Overview

概述

Done means verified, and verified names what was checked. Careful work is not a check: the two defects that ship in "obviously fine" changes were both caught, in this corpus's history, by the verification that almost got skipped.
完成意味着已验证，而验证需要明确说明检查了哪些内容。仔细的工作不等于检查：在过往案例中，那些在“显然没问题”的变更中出现的两个缺陷，都是被差点跳过的验证流程发现的。

The discipline

执行准则

  1. Run the proof, paste the result. The verify command from the pre-change checkpoint gets executed, and its actual output backs the claim. "Verified" is always "PASS (checked X and Y)", never a bare checkmark.
  2. Report faithfully, both directions. Tests that fail are reported with their output; steps that were skipped are named as skipped; and work that is done and verified is stated plainly without hedging. Underclaiming verified work wastes the reader's re-verification exactly like overclaiming wastes their trust.
  3. Distrust green. A green suite over code that cannot work means the suite does not run, does not cover, or cannot fail. When a result seems too clean for the change's size: confirm the test executed (run it alone, watch it appear), and confirm it can fail (break the code, watch it go red, unbreak it). A test that never ran and a gate that never fires are the two failure classes that produce confident wrong "done"s.
  4. Distinguish the tiers. Implemented (in the repo) is not deployed (live) is not externally verified (checked in the external system). Never claim a later tier from evidence of an earlier one.
  5. Lookback before declaring complete. Sweep the diff: no unrelated changes, no planning residue in code or comments, docs updated in the same change, every acceptance criterion actually met rather than approximately met.
  6. Independent verification for top-tier changes. The author of a change is the worst-placed person to verify it; for the project's declared critical paths (money, sales, stored data, safety, whatever the system must never get wrong) and for irreversible migrations, the verifier is someone or something that did not write the code. When no independent verifier is reachable in time, use the nearest substitute and name it as the weaker form it is; downgrading the check silently is the failure, downgrading it visibly is a decision.
  1. 执行验证流程，粘贴结果。 执行变更前检查点中的验证命令，用实际输出来支撑你的宣称。“已验证”必须表述为“通过（已检查X和Y）”，不能只是一个简单的对勾。
  2. 如实报告正反结果。 失败的测试要附上输出结果；被跳过的步骤要明确标注为已跳过；已完成并验证的工作要直白陈述，无需含糊其辞。对已验证的工作轻描淡写会浪费读者的重复验证精力，就像夸大其词会消耗读者的信任一样。
  3. 对全绿结果保持怀疑。 如果代码明显无法正常工作，但测试套件却显示全绿，说明套件未运行、未覆盖相关路径或无法检测出错误。当结果相对于变更规模显得过于完美时：确认测试已执行（单独运行该测试，观察其执行过程），并确认它能检测出错误（破坏代码，观察测试变红，再修复代码）。从未运行的测试和从未触发的门禁，是导致人们自信地做出错误“完成”宣称的两类原因。
  4. 区分不同阶段。 已实现（存入代码库）不等于已部署（上线），也不等于已外部验证（在外部系统中完成检查）。绝不能用前一阶段的证据来宣称已完成后一阶段的工作。
  5. 宣称完成前回顾检查。 全面检查差异：确保没有无关变更，代码或注释中没有残留的规划内容，文档在同一变更中已更新，每个验收标准都已实际满足而非近似满足。
  6. 顶级变更需独立验证。 变更的作者是最不适合验证自己工作的人；对于项目的关键路径（资金、销售、存储数据、安全等系统绝不能出错的环节）以及不可逆的迁移工作，验证者应是未参与代码编写的人或系统。如果无法及时找到独立验证者，使用最接近的替代方案，并明确说明这是较弱的验证形式；悄悄降低验证标准是失误，而公开说明则是一种决策。

Failing gates you own

负责你所维护的失败门禁

Any failing test in a gate you own gets fixed: attribute the origin first, then fix it regardless of whose it is. "Pre-existing" is a footnote in the report, never an excuse in the gate. The one exception is procedural, not evasive: a pre-existing red on the main branch that blocks an unrelated green fix gets surfaced with an offer to merge the green fix anyway, decided by the operator.
你所维护的门禁中任何失败的测试都要修复：先说明问题来源，然后无论归属如何都要修复。“预先存在的问题”只能作为报告中的脚注，绝不能成为门禁失败的借口。唯一的例外是流程性的，而非逃避责任：如果主分支上预先存在的失败测试阻碍了一个无关的正确变更上线，要提出该问题并提议合并正确变更，最终由运维人员决定。

Common mistakes

常见错误

  • Declaring done from the diff looking right. The diff looking right is the hypothesis; the verify command is the experiment.
  • Running the whole suite instead of the targeted proof, and reading "no new failures" as "my change works". A suite that never covered the path cannot vouch for it.
  • Verifying the happy path of a change whose risk is in the failure path.
  • "Tests pass locally" as the terminal claim for a change whose risk is environmental (config, migrations, permissions, prod data shape).
  • Fixing the test instead of the code when red is inconvenient. The test was the messenger.
  • 仅通过查看差异看似正确就宣称完成。差异看似正确只是假设，验证命令才是验证实验。
  • 运行整个测试套件而非针对性的验证流程，并将“无新失败”解读为“我的变更有效”。未覆盖相关路径的套件无法为变更提供保证。
  • 仅验证变更的正常路径，而忽略其风险所在的异常路径。
  • 将“本地测试通过”作为最终宣称，而变更的风险恰恰在于环境因素（配置、迁移、权限、生产数据格式）。
  • 当测试变红带来不便时，修改测试而非修复代码。测试只是问题的传递者。