From 59a67ea262070c91d9b411b3f2e7047010f6e142 Mon Sep 17 00:00:00 2001 From: Moritz Hoffmann Date: Tue, 1 Sep 2026 23:31:50 +0200 Subject: [PATCH] docs: codify when a comment earns its place Three rules the peek-execution work produced, added to the code-comment section. A stale comment asserting that `PeekResultIterator` could not be sent to another thread outlived its truth by months. It was read as fact rather than retested, and the peek stash was built to walk the trace a second time because of it. Constraints stated in comments now have to be checked when written. The other two cover what the section left implicit. A sentence earns its place by changing what a maintainer would do, not by being true, and rewording a paragraph while keeping every fact in it is not editing. "X rather than Y" informs only when Y is what a reader would otherwise assume; elsewhere Y is unfalsifiable and rots silently, since the code can move to Y with the sentence still reading correctly. Also narrows "why the obvious alternative was not taken", which reads as licence to justify every choice, to the alternative a reader would assume. --- AGENTS.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a7beb5751ec78..8a4b9a0e21226 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -146,8 +146,9 @@ Spend comments on the non-obvious: concurrency and async hazards (races, lease/handle expiry, values that must not be held across an await point), ordering constraints ("X must happen before Y, else Z"), invariants whose violation panics or corrupts data, restart/recovery semantics, the origin of -magic constants, and why the obvious alternative was not taken. Idiomatic code -(match arms, iterator chains, getters, logging) needs none. +magic constants, and why the alternative a reader would otherwise assume was +not taken. Idiomatic code (match arms, iterator chains, getters, logging) needs +none. A doc comment is the caller's contract: a one-sentence summary, then only the invariants and semantics a caller must know. A self-evident public item needs @@ -176,6 +177,26 @@ placement carries the structure. Performance claims in comments should state a constraint or a measured number, not unverifiable color ("the compiler can autovectorize this"). +Before keeping a sentence, ask whether a maintainer would get something wrong +without it. If deleting it changes nothing they would do or believe, delete it, +however true it is. Prefer deleting a sentence to rewording it: shortening the +words while keeping every fact is not editing. + +A comment that asserts a constraint ("X is not possible, because Y") has to be +checked when it is written, by a compile probe, a test, or a pointer to what +enforces it. An unchecked constraint outlives its truth. It reads as fact, +nobody retests it, and later work gets designed around a limit that is no +longer there. Where the constraint cannot be checked, write what was observed +instead of what is impossible. + +Avoid "X rather than Y" unless Y is what a reader would otherwise assume. Where +Y is not a live prior it is unconstrained and unfalsifiable, and it rots +silently, since the code can move to Y with the sentence still reading +correctly. Where Y is a real trap, assert the failure instead of the contrast +("awaiting here deadlocks, because the caller is a `Drop`"), which gives the +claim truth conditions. A failure mode that cannot be named means the comment +records a preference and not a reason. + The same economy applies to tests: a test whose name and assert messages state the property needs no doc comment. Keep test docs for non-obvious setup, fixtures whose shape encodes the scenario, and multi-phase protocols.