Write Durable Code Comments

Treat each warranted comment as an experimental handoff to a future maintainer.

Workflow

1. Identify a verified local decision that a reasonable maintainer could undo because its constraint is invisible.
2. Prefer clearer code, types, assertions, or tests. Put cross-cutting decisions in repository guidance or a design document.
3. If the constraint remains hidden, write the smallest adjacent comment that states the constraint and the consequence of violating it. State rationale only when supported by verified evidence.
4. Update affected comments and validate the final behavior.

Guardrails