documentationlisted

# Documentation Microsoft contract-first conventions. Documentation states the **contract** — what something does and why — never how it works inside. ## Why the rules are subtractive Code changes; the comment beside it usually does not. Over time documentation lies, and readers trust it anyway — a stale comment is worse than no comment, because it actively misleads. Two habits follow, and every rule below is one of them applied: **Keep the surface small.** Less prose has less to rot. A comment is a last resort, not a first step: before writing one, ask whether a sharper name, a smaller function, or a named type would carry the meaning instead. Prose is for the residue that code genuinely cannot express. **Keep each fact in one place,** next to the code that owns it, so there is exactly one thing to update. When the signature, the type, or a test already states something, the prose must not restate it. ## The bare-minimum rule The signature already carries the name, parameter names and types, return type, and modifiers (`readonly`, `?`, `async`). Documentation adds only what a reader cannot infer from it: intent, units, ranges, defaults, edge-value meaning, error cases, invariants. Every public member still gets a brief summary, so generated docs and IDE tooltips have content — one short sentence carrying intent, never a paraphrase of the signature. For `@param` and `@returns` specifically, **drop the tag entirely when it would only restate the signature.** A tag ear