Name Things Once
Settles what everything is called before the code is written, so one idea does not arrive under four names.
When to reach for it
Just before writing a feature that introduces new concepts — the moment you notice you and the agent using different words for the same thing.
What changes
- The agent lists the nouns and verbs of the feature and picks one name for each, before a file is created.
- Names already used in the codebase win over new inventions, so the feature reads like it belongs there.
- You get to veto a name while it costs a sentence, instead of after it has spread to a database column, an API field and six components.
- Words doing two jobs get caught and split, so you do not end up with one 'status' that means three different things depending on the layer.
- Every later file in the feature uses the agreed list — variables, types, routes, labels and test names included.
Pairs with
- No New VocabularyStops the agent coining terms that compete with the words your codebase already uses.
- Borrow the ShapeStarts new code from the closest existing file in your repo instead of from a blank page.
- Copy the NeighboursMakes new code look like the code already around it, instead of like whatever the agent prefers.
Name Things Once
Decide the vocabulary before the first file. Renaming is cheap in an editor and expensive in a database.
1. List the things
Write the nouns this feature introduces — the entities, the states, the events. Give each one name and one sentence of definition. If two nouns need the same sentence, you have one noun.
Then the verbs: what can be done to each noun. Same rule, one name each.
2. Check the codebase before inventing
Search for every candidate name. There are three outcomes:
- It exists and means the same thing — use it exactly as spelled, including its casing.
- It exists and means something else — pick a different word. One word with two meanings is the expensive mistake this whole exercise exists to prevent.
- It does not exist — you are free, so choose the plainest word someone using the feature would say out loud.
3. Split the overloaded words
Status, item, data, info, handle, and process usually cover several ideas at once. If one word is doing two jobs, name both jobs. A subscription that is both active and paid needs two fields, not one adjective that means whichever you were thinking about.
4. Apply the list to every layer
The agreed names govern variables, types, database columns, JSON fields, routes, user-visible labels and test descriptions. Same concept, same word, everywhere. A translation layer between two names for one thing is a bug waiting for a deadline.
5. Show the list before writing code
Ten to fifteen lines. The user reads it in twenty seconds and catches the name that would have been wrong.
Rules
- Do not introduce a synonym for convenience. If the entity is an order, never call it a purchase in one function because it read better there.
- Do not use a name whose meaning depends on where you are standing. "Current" and "target" only make sense next to each other.
- Do not encode the type in the name when the language already tracks types.
- Do not rename halfway through. If a name turns out wrong, change every occurrence in one pass, or keep the wrong one until the feature lands.