naming-as-designlisted

# Naming-as-Design ## Overview **Core principle:** Naming is not decoration applied after the design — naming *is* the design. A thing you can't name cleanly is usually a thing that isn't cleanly *one thing*. Use the struggle to name as a signal about the structure, and renaming as a tool to fix it. When the right name is obvious, the design underneath is sound. When no name fits, the name isn't the problem — the shape is. ## The Diagnostic A hard-to-name thing is telling you something. Read the signal: | Naming symptom | What it usually means | The fix | |---|---|---| | The name needs "and" (`parseAndValidate`) | It does two things | Split it into two named things | | Only a vague name fits (`data`, `manager`, `process`) | Its responsibility is vague | Sharpen the responsibility, then name it | | The name lies about what it does now | Behavior drifted from intent | Rename to the truth, or restore the intent | | You reach for a comment to say what it *is* | The name is underperforming | Move the comment's content *into* the name | | Same concept, three different names across the file | You haven't decided what it is | Pick one true name, use it everywhere | ## The Practice 1. **Name for the reader, from the outside.** A name describes what a thing *is* or *returns*, in the caller's vocabulary — not how it's implemented inside. `activeUsers`, not `filteredList`. 2. **Make the name carry the weight a comment would.** `secondsUntilExpiry` needs no comment; `t` plus