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
- 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.
- Make the name carry the weight a comment would.
secondsUntilExpiry needs no comment;
t plus a comment does the same job worse. Every comment explaining a name is a naming bug.
- Let a failure to name change the code, not just the label. If nothing fits, don't force a
bad name — split, merge, or reshape until a good name becomes available. The name comes last
because it's the design's signature.
- One concept, one name; one name, one concept. Synonyms drifting across a codebase
(
fetch/get/load/retrieve for the same act) make readers hunt for distinctions that
aren't there. Consistency is kindness.
Quick Reference
| Weak name |
Why it's weak |
Stronger |
data, info, obj |
Says nothing |
invoice, userProfile |
tmp, x, result |
No meaning |
remainder, parsedDate |
handle, process, doIt |
Verb without object |
retryFailedJobs, renderInvoice |
manager, helper, util |
Junk-drawer |
Name the actual job it does |
flag, check, isValid |
Which flag? valid how? |
hasUnsavedChanges, isPastDue |
getData() returning a filtered subset |
Hides the filter |
getActiveUsers() |
Common Mistakes
- Naming by implementation, not by meaning.
sortedList breaks the day you switch to a set;
rankedCandidates survives. Name the what, not the how.
- Renaming the label without re-reading the passage. A name is only better if the code around
it reads better. Names live in sentences; read the sentence.
- Encoding types into names (
strName, listUsers) when the language already tracks types.
The name should add meaning the type can't.
- Accepting a bad name because "it's just a local." Locals are where the reader spends the
most time. They deserve the most care, not the least.
Relationship to Other Skills
This is the whittler's second pass, after subtraction-first (a good name often deletes a
comment or a helper). Renaming for the reader flows directly into reading-like-prose.
1---2name: naming-as-design3description: Use when code feels tangled or needs a comment to explain what something is, when reaching for a name and nothing fits, or when a name is vague (data, tmp, handle, process, manager, util, doStuff) and the fuzziness hides a fuzzy design4---56# Naming-as-Design78## Overview910**Core principle:** Naming is not decoration applied after the design — naming *is* the design.11A thing you can't name cleanly is usually a thing that isn't cleanly *one thing*. Use the struggle12to name as a signal about the structure, and renaming as a tool to fix it.1314When the right name is obvious, the design underneath is sound. When no name fits, the name isn't15the problem — the shape is.1617## The Diagnostic1819A hard-to-name thing is telling you something. Read the signal:2021| Naming symptom | What it usually means | The fix |22|---|---|---|23| The name needs "and" (`parseAndValidate`) | It does two things | Split it into two named things |24| Only a vague name fits (`data`, `manager`, `process`) | Its responsibility is vague | Sharpen the responsibility, then name it |25| The name lies about what it does now | Behavior drifted from intent | Rename to the truth, or restore the intent |26| You reach for a comment to say what it *is* | The name is underperforming | Move the comment's content *into* the name |27| Same concept, three different names across the file | You haven't decided what it is | Pick one true name, use it everywhere |2829## The Practice30311. **Name for the reader, from the outside.** A name describes what a thing *is* or *returns*,32 in the caller's vocabulary — not how it's implemented inside. `activeUsers`, not `filteredList`.332. **Make the name carry the weight a comment would.** `secondsUntilExpiry` needs no comment;34 `t` plus a comment does the same job worse. Every comment explaining a name is a naming bug.353. **Let a failure to name change the code, not just the label.** If nothing fits, don't force a36 bad name — split, merge, or reshape until a good name becomes available. The name comes *last*37 because it's the design's signature.384. **One concept, one name; one name, one concept.** Synonyms drifting across a codebase39 (`fetch`/`get`/`load`/`retrieve` for the same act) make readers hunt for distinctions that40 aren't there. Consistency is kindness.4142## Quick Reference4344| Weak name | Why it's weak | Stronger |45|---|---|---|46| `data`, `info`, `obj` | Says nothing | `invoice`, `userProfile` |47| `tmp`, `x`, `result` | No meaning | `remainder`, `parsedDate` |48| `handle`, `process`, `doIt` | Verb without object | `retryFailedJobs`, `renderInvoice` |49| `manager`, `helper`, `util` | Junk-drawer | Name the actual job it does |50| `flag`, `check`, `isValid` | Which flag? valid how? | `hasUnsavedChanges`, `isPastDue` |51| `getData()` returning a filtered subset | Hides the filter | `getActiveUsers()` |5253## Common Mistakes5455- **Naming by implementation, not by meaning.** `sortedList` breaks the day you switch to a set;56 `rankedCandidates` survives. Name the *what*, not the *how*.57- **Renaming the label without re-reading the passage.** A name is only better if the code around58 it reads better. Names live in sentences; read the sentence.59- **Encoding types into names** (`strName`, `listUsers`) when the language already tracks types.60 The name should add meaning the type can't.61- **Accepting a bad name because "it's just a local."** Locals are where the reader spends the62 most time. They deserve the most care, not the least.6364## Relationship to Other Skills6566This is the **whittler**'s second pass, after **subtraction-first** (a good name often deletes a67comment or a helper). Renaming for the reader flows directly into **reading-like-prose**.
atgreen