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 earns its place when it answers: what unit? what range or clamp? what default when omitted? what does an edge value mean (0 disables, -1 unlimited, empty = all)? what does null signify versus throwing?