The art of naming: a name is judged by whoever uses it

The monthly report said two hundred and fourteen clients. Billing said one hundred and ninety. Nobody had touched the numbers and both came from the same database.

The word client meant two things. In the CRM it was anyone who had ever left their details. In billing it was anyone with at least one invoice issued. Neither definition was wrong. What was wrong was that they shared a name, because the shared name made everyone believe for two years that they were talking about the same thing, and the meetings where decisions were made about “the clients” were deciding about two different populations depending on who had brought the report.

There’s an old joke in the trade: there are only two hard problems in programming, cache invalidation, naming things and off-by-one errors. The joke is in the miscount. The truth is in the second one.

Naming is drawing a border

When you call something user you are asserting that it is a user, and not an account, or a profile, or a session, or a contact. The word cuts up the world. And the cut propagates: everyone who reads that name will think inside the border you drew, even if it was drawn in the wrong place.

Which is why a bad name isn’t a cosmetic problem. It’s a false hypothesis embedded in the code, which others inherit without noticing they’re inheriting it.

The argument has a whole dialogue to itself

Plato gave the matter an entire text, the Cratylus, and staged it as a fight between two positions anyone recognises today without having read it.

Hermogenes holds that names are a matter of agreement. None is more correct than another by nature; whatever we agree to call something, that’s what it is. And if we change our minds tomorrow, we change the name and nothing has happened. It’s exactly what gets said to close a review: “it’s just a name, we can rename it later.”

Cratylus holds the opposite: there is one correct name for each thing, a name that belongs to it, and the rest are noises. It’s exactly what happens to whoever has been stuck for twenty minutes in front of a variable, hunting for the exact word as if only one existed and it were hiding.

Socrates leaves both of them looking bad, and how he does it is the interesting part.

To Hermogenes he answers that a name is a tool — it serves to teach something to someone and to separate one thing from another — and that tools are not a matter of indifference. A weaver’s shuttle separates the threads; you can make it in whatever shape you like, but not in any shape, because there are shapes you cannot weave with. Agreement isn’t enough: if the name doesn’t separate what needs separating, it’s no good, however unanimously we’ve agreed to use it.

To Cratylus he answers something more uncomfortable. If names were correct by nature there could be no wrong name — the badly named would simply be unnamed — and that’s false, because people misname things every day. Names were given by first namers who could be mistaken too. From which comes the conclusion that closes the dialogue and ought to be framed on the wall of any team: it is better to learn things from the things themselves than from their names.

Translated into the trade: don’t learn a system by reading its identifiers. They were put there by someone who was working the thing out as they typed, and studying their names means inheriting their mistakes in the same package as their insights, with no mark to tell them apart.

Who validates a name

The shuttle argument yields the most useful rule I know on this.

Socrates asks who judges whether a shuttle is well made, and the answer isn’t the carpenter who made it: it’s the weaver who uses it. Whoever makes the tool knows how they made it; only whoever uses it knows whether it works.

Names work the same way, and it’s brutal for the writer. A name is validated by whoever reads it, not by whoever chose it. If you have to open the implementation to find out what a variable holds, the name has already failed, however elegant it looked to its author and however good their reasons were. The author had the whole context in their head when they picked the word; that context doesn’t travel with the code.

Which is why review is the only place a name can really be judged, and why “I don’t understand what this is” is technical information, not a complaint.

Prodicus and the trade of telling words apart

Among the sophists there was one, Prodicus of Ceos, who specialised in something his contemporaries found ridiculous: separating words that look like synonyms. He distinguished being pleased from enjoying, willing from wanting, courage from boldness. Plato mocks him more than once, and you can see the joke: from outside, it looks like a man spending his life on shades of meaning.

It’s the same work as deciding whether client, account, contact and user are four things or one thing in four costumes. And it produces the same face in the meeting — someone arguing about words while there’s work to do — until the month the report says two hundred and fourteen and billing says one hundred and ninety.

That’s where you see what Prodicus was defending and his contemporaries weren’t: that two words used as if they were one end up hiding the fact that there are two things underneath. The distinction isn’t invented by making it explicit. It was already there, operating and invoicing, just without a name.

Naming is the last stage of understanding

Here’s the part that took me longest to accept. When I can’t find a good name, it’s almost never a vocabulary problem. It’s that I still don’t properly understand what the thing is.

The elusive name is a symptom. data, info, manager, helper, process, handle are the residue of a concept that never got finished. Forcing yourself to a concrete name forces you to decide what it is, and sometimes that decision reveals the design was split wrong: that the manager was doing three things that should live in three places, and that none of the three had a name because none of the three had ever been seen on its own.

Which is why naming doesn’t happen at the end, like painting a wall once everything’s up. The good name usually arrives at the same time as the good structure, and when it doesn’t arrive, what’s missing isn’t creativity: it’s understanding the problem.

Rules I use

• Name for what it is, not for how it’s built. orderedItems survives a change of structure; itemsArray dies with it.
• One name, one concept. If the same word means two things in two modules, you have two concepts disguised as one, and sooner or later someone will add them together.
• Length pays when the life is long. A variable that lives three lines can be called i. A domain concept read a hundred times deserves to be written out.
• Distrust the comfortable names. utils, common, misc are drawers where judgment goes to die. What you don’t know where to put is what you don’t yet understand.
• Read it out loud. If saying the call aloud doesn’t make sense in a human language, the name is lying somewhere.
• Write the definition in one line. If it doesn’t fit, or it has an “and” in the middle, it isn’t a concept: it’s two.

Why it matters this much

A program is a theory about a piece of the world written in names. If the names are honest, the theory can be read, argued with and corrected. If they lie, every line resting on them inherits the lie without knowing, and the error shows up in no test, because it isn’t an arithmetic error: it’s an error in how the world was divided up.

The Cratylus doesn’t settle the argument, which is probably why it’s still read. It leaves something better than an answer: that names are neither sacred nor indifferent. They are tools made by someone who could be wrong, and they are judged by whether they separate what needs separating.

Naming well isn’t cosmetics. It’s the cheapest way to think clearly, and the only one that also stays written down.