Naming identifiers so that code reads as intent

Goal

Let a reader understand a function or variable from its name without reading its body, and let a searcher find every use of a concept by grepping one word.

Prerequisites

A shared vocabulary for the domain (a glossary in the README or ADRs) and a tool that renames safely across the codebase.

Steps

1. Name by role and meaning, not by type or mechanism: retry_deadline rather than dt2, unpaid_invoices rather than list1.
2. Scale length with scope: a loop index can be i; a module-level constant or a public function needs a full description.
3. Use one word per concept throughout (fetch or load or get, not all three), and the domain's own terms.
4. Make booleans read as predicates (is_expired, has_children) and functions as verbs or verb phrases; make collections plural.
5. Avoid encodings (Hungarian prefixes, type suffixes) and avoid names that lie after a change (temp_fix_v2 that became permanent).
6. When a name needs a comment to explain it, rename instead; when understanding improves, rename immediately with the tool and commit separately.

Expected result

Fewer comments, shorter reviews, and searches that find exactly the concept's uses.

Limits and test basis

Naming conventions of the language and framework win over personal taste. Public API names cannot be changed freely; choose them with more care. No measurement is claimed.