There's a famous joke: the two hardest problems in computer science are cache invalidation, naming things, and off-by-one errors. The joke lands because the naming part is true. Naming is genuinely one of the hardest and most underrated problems in software — and it matters far more than it seems, because a good name is documentation that never goes stale, while a bad one is a bug waiting to happen.
Here's why naming is so hard, why it matters so much, and how to do it well.
Naming is genuinely one of the hardest problems in software — and getting it right matters enormously.
Why it matters:
Naming is hard because it forces you to deeply understand what a thing actually is.
Naming seems trivial — just pick a word — but it's hard for a deep reason: to name something well, you have to understand precisely what it is. A good name captures the essence of a thing, its purpose and role, in a word or two. That requires real clarity about what the thing actually does, what it's responsible for, and how it differs from everything around it. The struggle to find a good name is usually a sign that you don't yet fully understand the thing you're naming.
That's why naming is one of the hardest problems rather than a clerical afterthought. It's not about vocabulary; it's about comprehension. When a name is hard to find, the difficulty is diagnostic — it's telling you the concept is muddy, the responsibility unclear, or the abstraction wrong. Often the act of naming forces a better design, because you can't name cleanly what isn't clearly conceived. The hardness of naming is the hardness of understanding, surfacing in a single word.
The reason naming matters so much is that names are the primary way humans reason about code. A good name does the work of documentation, with a crucial advantage: it can't go stale. Comments and docs drift out of sync with the code they describe, but a name lives in the code and is read every time the thing is used.
| Good name | Bad name |
|---|---|
| Documents intent inline | Requires extra docs to explain |
| Always accurate (it's the code) | Drifts from reality, misleads |
| Reduces cognitive load | Multiplies confusion |
| Reveals what a thing is | Hides or misrepresents it |
A well-named function or variable explains itself wherever it appears, so a reader understands the system faster and more reliably. This is the same principle behind documentation developers actually read: the best documentation is the kind that lives where it's needed and stays true. Good names are documentation embedded in the code itself, accurate by construction and impossible to ignore.
If good names reduce cognitive load, bad names actively create problems. A misleading name — one that says a thing does X when it actually does Y — doesn't just fail to help; it sends readers in the wrong direction. People reason about code based on what things are called, so a name that misrepresents reality plants a false belief that leads directly to bugs.
This is what makes bad naming dangerous rather than merely untidy. A variable named for what it used to hold, a function whose name implies a side effect it doesn't have (or hides one it does), a type whose name suggests the wrong concept — each is a trap for the next person, who will reasonably trust the name and be wrong. Bad names multiply cognitive load and cause misunderstandings that surface as defects. The cost of a bad name is paid repeatedly, by everyone who reads it, for as long as it survives. That's why naming isn't cosmetic — a bad name is a bug waiting to happen.
Good naming is a skill you can develop with a few principles:
The throughline is that good naming follows from clear understanding: you can't name well what you don't understand well, and the effort to name forces the understanding. Treat the struggle to name as a design signal, not an annoyance — it's often pointing at a concept that needs sharpening. Done well, naming is one of the highest-leverage things you can do for a codebase's clarity, which is exactly the no-code-is-the-best-code instinct applied to comprehension: less confusion, less to explain, fewer bugs.
Q: Is naming really one of the hardest problems in software? Yes, and not as a joke. Naming is hard because to name something well you must understand precisely what it is — its purpose, role, and how it differs from everything around it. A good name captures that essence in a word or two, which requires genuine clarity. The struggle to name is usually a sign you don't yet fully understand the thing, which is why naming is a comprehension problem, not a clerical one.
Q: Why do names matter so much if they're just labels? Because names are how humans reason about code, and a good name is documentation that can't go stale — it lives in the code and is read every time the thing is used, unlike comments that drift out of sync. A good name explains itself wherever it appears, reducing cognitive load. A bad one actively misleads, planting false beliefs that lead to bugs. Names aren't just labels; they're the primary interface between a system and the people who understand it.
Q: How do I get better at naming? Name what a thing is (its purpose and role), not how it works; be precise rather than clever; and treat difficulty naming as a signal that the underlying concept or design is muddy. Avoid names that mislead — a wrong name is worse than a vague one because it actively deceives. And rename freely as your understanding improves. Good naming follows from clear understanding, so the effort to name well often forces a better design.
Naming is genuinely one of the hardest problems in software, because naming something well requires understanding precisely what it is — and the struggle to find a name usually means the concept itself is still muddy. It matters enormously: a good name is documentation that never goes stale, read every time the thing is used, while a bad name actively misleads and becomes a bug waiting to happen.
Name what a thing is, be precise over clever, treat naming difficulty as a design signal, avoid names that deceive, and rename as your understanding sharpens. Good naming follows from clear thinking and produces clearer systems — which is why it's worth treating as one of the highest-leverage things you do, not an afterthought.
No following, no network, no luck. Just an unglamorous system I ran for eighteen months. Here's exactly what I did.
I went from 200 to 11,000 subscribers without hiring anyone. AI didn't write my newsletter — it did everything around it.
I chased big, audacious goals for years and burned out every time. Then I built my whole life around wins so small they felt like cheating.
Comments
Sign in to join the conversation
No comments yet. Be the first to share your thoughts!