There is an old joke that there are only two hard problems in computer science: cache invalidation, naming things, and off-by-one errors. The joke endures because the middle item is so quietly true. Naming is the part of programming everyone does constantly and almost no one does well, and a codebase full of bad names is slower to read, harder to change, and more prone to bugs than one where things are named with care. But "name things well" is useless advice, because the interesting question is not the abstract ideal — it is how names actually go wrong. Bad names come in species, each with its own habitat and its own damage. This is a field guide to the most common of them: how to recognise each one in the wild, why it is harmful, and how to correct it.
The Lie
Habitat: everywhere. Danger level: extreme.
The most dangerous species of bad name is the one that is actively false — a name that says the code does one thing when it in fact does another. A function called getUser that also silently updates a login timestamp; a variable called count that actually holds a list; a flag called isValid that is set when something is invalid. The Lie is the deadliest bad name because it does not merely fail to help; it actively misleads, and a reader who trusts the name will reason incorrectly about the code and introduce bugs on the basis of a false premise.
The Lie is especially insidious because it often starts out true and becomes a lie through drift. A function named accurately when written accumulates side effects and responsibilities over time until its name no longer describes it, and nobody updates the name because renaming feels risky and low-priority. The correction is unglamorous but essential: a name must always tell the truth about what the code does, and when the behaviour changes, the name must change with it. If you can only fix one category of bad name, fix this one — a name that lies is worse than no name at all, because at least an obscure name forces the reader to check.
The Cryptic Abbreviation
Habitat: old code, dense algorithms, keystroke-averse authors. Danger level: moderate but pervasive.
This species needs no introduction: d, tmp, mgr, usrCtxHdlr, flt2. It is born from the false economy of saving keystrokes at the cost of readability, and it is everywhere because typing a short name feels efficient in the moment the code is written. The damage comes later and lands on someone else: every reader who encounters d has to stop, hunt for where it was defined, and work out what it means, paying a small tax of interruption every single time. Code is read far more often than it is written, so a name that is fast to type but slow to understand is a bad trade, repeated on every reading.
Not all short names are guilty — a loop counter i in a three-line loop is understood by universal convention, and a genuinely local, short-lived variable can be brief without harm. The Cryptic Abbreviation becomes a problem when the name outlives its tiny context or when the abbreviation is non-obvious. The correction is simply to spell it out: distance instead of d, userContextHandler instead of usrCtxHdlr. Modern editors autocomplete, so the keystroke saving is largely imaginary anyway. The full word costs a moment to write and saves a moment on every future read, which is a trade that always pays off.
The Vague Noun
Habitat: quickly-written code, catch-all utilities. Danger level: moderate; grows with codebase size.
The Vague Noun is a name that is technically accurate but tells you almost nothing: data, info, manager, handler, object, item, value, stuff. These names are not wrong, exactly — the thing probably is data — but they are so generic that they fail to distinguish this data from any other, forcing the reader to look elsewhere to find out what it actually contains. A function that takes data and returns result has told you nothing about what it does; the names are placeholders that were never replaced.
The Vague Noun thrives because generic names are always easy to reach for. Faced with a variable holding a user's shipping details, data requires no thought, while shippingAddress requires you to actually decide what the thing is. That small act of deciding is exactly the value a good name provides — it forces clarity about the concept, and passes that clarity to every future reader. The correction is to name the specific thing rather than its general category: not data but invoiceLineItems, not manager but subscriptionRenewalScheduler. The more precise the name, the more the code documents itself, and the less the reader has to reconstruct meaning from context.
The Overload
Habitat: shared vocabularies, large teams, long-lived codebases. Danger level: subtle but corrosive.
The Overload is a name that means different things in different places — the same word used for genuinely distinct concepts, so that order refers to a customer's purchase in one module and to sort direction in another, or user means an authenticated account here and a database row there. Each use may be locally reasonable, but the collision means the reader can never fully trust their understanding of the word; they must re-establish which meaning applies every time they cross a boundary. A shared vocabulary that does not mean the same thing everywhere is not really a shared vocabulary at all.
This species is harmful precisely because it undermines the thing names are supposed to provide: a stable, shared understanding. When a term is overloaded, the mental model built in one part of the code becomes a trap in another, and subtle bugs arise when a developer assumes one meaning while the code intends the other. The correction is a discipline about vocabulary: within a given domain, a word should mean one thing, and distinct concepts should get distinct names even when it feels verbose. sortDirection and purchaseOrder are longer than order, but they never collide, and the small cost in length buys a large gain in clarity — the same kind of quiet correctness we examined in the character encoding bugs that still haunt modern software, where an ambiguous shared assumption causes trouble far from where it was made.
