Name it right the first time
I kept a thesaurus for naming things, and not to find prettier words. Finding the name is how I find out whether I understand the concept I am about to build. Giant Context, the website platform I build, is two months old, and no design habit has paid off more than sweating the names.
The name comes before the thing
Before a line of a new package exists, its name forces the questions that matter. What job does this do? What belongs inside it? What must never bleed into it? If I can't land the name, I haven't finished thinking, and building anyway means building without the answers. The package ships its confusion.
That is what the thesaurus was actually for. Hunting for the exact word is drawing the boundary. The difference between calling something media and calling it files is not vocabulary, it is a decision about what the system will and will not carry. Naming is the cheapest design review that exists, and it is available before the first commit.
Code grows in the shape of its name
A name is not a label on the package. It is instructions for everyone who adds to it. Every later decision about where code belongs gets judged against the word. Does this go in ui? Is this core's job? Name a package well and those questions answer themselves for months. Name it wrong and every one of those small answers lands slightly off, because people build toward what the word says, not toward what you meant.
Get names right on day one because the steering starts the minute the name exists. And the steering has doubled. The AI tooling I build with reads this codebase by its names and takes every one of them literally. When names are consistent (standard casing, standard structure, the same word meaning the same idea everywhere), the tooling writes new code that matches, and the consistency compounds. When a name lies, the lie spreads at generation speed. We used to name things for other eyeballs. Now the names are load-bearing for machines that never skim.
When a name lies, the lie spreads at generation speed.
The rules on the wall
Sweating names does not mean improvising them. The mechanical half is pinned down in the codebase's standards doc, and the agents and I both follow it. From that doc:
The naming conventions, from the standards doc
| Element | Convention | Examples || ---------------- | -------------------------- | ------------------------ || React Components | PascalCase | Button, UserProfile || Functions | camelCase, max 3 words | getData, handleClick || Variables | camelCase, max 3 words | userId, isActive || Constants | camelCase | defaultValue, maxRetries || Types | PascalCase + "Type" suffix | UserType, ConfigType || Interfaces | PascalCase + "Props" | ButtonProps |
STRICTLY FORBIDDEN:- SCREAMING_SNAKE_CASE - Never use this anywhere- Long names - Maximum 3 words, aim for 2- Abbreviated names that aren't obvious - Use `user` not `usr`The word budget is the thesaurus rule in disguise. A two-word name has no room to hedge, so it forces you to find the word that actually fits. The rest is consistency for the second reader, who never skims and never guesses.
Right names go stale
Two months of this platform's history, in five renames.
portal → core
The shared connector every app bolts onto.
design-system → ui
Just the UI kit.
media library → files
A document is not media.
media service → files service
Renamed to match.
triage → brain
It builds features now, not just sorts errors.
None of these were naming mistakes. Portal was true until the platform grew into compartmentalized apps and the package became the connector they all bolt onto. Media was true until the AI arrived and started feeding on documents, and a document is not media. Triage was true until the service stopped sorting errors and started building the features customers ask for. The product evolved. The names stood still. A name does not have to be wrong to become wrong.
Manage names like you manage dependencies
Names need maintenance, the same as anything else that can silently go stale. The check is one question, asked whenever a package's job shifts. Does the name still describe the role? The day the answer is no, the name has started steering wrong, and everything new built under it aims at the concept that no longer exists. Rename the day the name stops telling the truth, because names steer.
In my codebase that correction is cheap (one repository to sweep, most references generated from schemas, replaced code deleted the same day), so a stale name rarely survives the week it goes stale:
One import, renamed
import { Layout } from "@giantcontext/portal"; // before Dec 25import { Layout } from "@giantcontext/core"; // afterIf renames are expensive where you work, that is not permission to skip the maintenance. It is a bigger argument for the day-one sweat, because you will be living with your first guess for years.
Naming is day-one, coding-101 stuff, and it is still the design decision I sweat hardest, because the audience for a good name doubled. Keep the thesaurus.
Have questions?
If you're interested in my work or Giant Context, contact me!