- Write plain subject-verb-object sentences. Avoid compressed rhetorical constructions like "the constraint the diagram glosses" or "waiting for that confirmation is what keeps X honest" — say "the diagram doesn't show X." These read as LLM-ese, not natural technical writing.
- One idea per sentence. Assume the reader is context-switching and skimming; they should never have to reread a sentence to work out what it claimed.
- Don't bury a fact in a trailing clause of a sentence about something else. If a change matters, state it outright with its file path, as its own sentence.
- Make every list item self-contained: lead with the plain-language topic ("the sync freeze bug"), never a bare code or section reference ("A2", "task 13", "§6"). A reference may follow in parentheses for lookup, but the item must be readable without the source document.
- Use one consistent name for a thing throughout a discussion instead of alternating references to it.
- When reporting a concern, lead with a plain one-sentence statement of what is (or isn't) wrong. If something is wrong, say so directly; if nothing is wrong, don't hedge in a way that implies otherwise. Don't obscure the point behind file:line citations the reader doesn't have in front of them.
- Keep doc comments to one or two lines. State only what the code can't show; drop where a value comes from, secondary rationale, and restatements of mechanics readable in the function body. Go longer only for genuinely non-obvious constraints.
- State behavior and practical consequence ("without this wait the last words can be lost"), not design philosophy ("owns the distinction so X and Y can't drift apart"). No grandiose narration of a comment's own significance.
- When commenting something unusual (a cast, a workaround, an apparent no-op), structure it as facts about the mechanism in the order the code encounters them, then note the one gap or caveat plainly. Don't write it as an argument defending the choice ("this is safe because…", "this is only needed because…"), and avoid evaluative words about the code's own trick ("load-bearing"). A defense-shaped comment addresses a reviewer, not the next reader — and it reads as removable once the argument is accepted.
- When citing a "rule" (React, TypeScript, HTTP, …), state the actual runtime invariant, not the community folklore version (e.g. the Rules of Hooks require stable unconditional call order — they don't "forbid loops"). Weigh lint/tooling/compat considerations as tradeoffs, not laws.