Rule 26 of 38 · Chapter IV — Write for the Next Developer

Names are documentation

Why this rule exists

A name is the first and most frequent documentation anyone reads, and it travels everywhere the value goes. A precise name answers what something is and why it exists before the reader looks at a single line of logic; a vague or misleading one quietly lies at every call site. Naming is hard because it forces you to actually understand what a thing is — and that difficulty is the work, not a distraction from it.

In practice

Name things for what they mean, not their type or shape: elapsedMs, not time; pendingInvoices, not list2. Let scope guide length — a loop index can be i, but a value that lives across a whole module earns a full, descriptive name. When a good name won't come, treat it as a signal that the concept itself is unclear or doing too much, and fix that first.

When it doesn't apply

Established conventions win over novelty: i, j for indices, well-known domain abbreviations, and the idioms of your language or framework are clearer precisely because readers already know them. Don't rename to satisfy a rule when the short form is the more familiar one.