Naming things

Last week I sat looking at a function argument for what I’d guess was 20 minutes. It held a list of things a customer had chosen. items was wrong because there were already items elsewhere meaning something different. selection was vaguer than what I meant. basket implied a whole checkout apparatus that didn’t exist yet. chosenProducts was accurate and horrible.

I felt guilty about the 20 minutes, in the specific way you feel guilty about time that produces no diff. And then partway through I realized the reason none of the names fitted was that I hadn’t actually decided what the thing was. It was a list of products in one flow and a list of product-and-quantity pairs in another, and I’d been carrying that ambiguity around for two days without noticing it, because the code compiled either way.

The name was the first thing to notice.

It isn’t a vocabulary problem

That’s the whole argument, really. Naming feels like a language exercise, like you’re rummaging for a better synonym, and that framing is why it feels like a waste of time. Under it, “I can’t think of a name” means “my thesaurus is inadequate,” and the obvious response is to slap something on and move on.

But nearly every time I’ve been genuinely stuck on a name, the actual situation was that the thing didn’t have a clear identity yet. It did two jobs. It meant one thing on Tuesday and something adjacent on Thursday. It was “whatever I needed to pass to this other function.”

"I can't think of a name for this" is almost always "I haven't decided what this is," wearing a disguise that lets you skip past it.

Which makes naming the cheapest design review available. It runs continuously, costs nothing, and it fails loudly at exactly the point where your model of the problem is muddled. The compiler won’t tell you that. The tests won’t tell you that. The name will, if you let it.

The words that mean nobody decided

There’s a family of words that show up when this has happened and nobody stopped.

data. info. item. object. thing. stuff, occasionally, in mine, at 5:30. Manager, Helper, Handler, Processor, Service, Util. A file called utils.js or a partial called _misc.scss.

These aren’t bad names because they’re vague, exactly. They’re bad because they’re a category rather than an identity: userData tells me the type of the container and nothing about what’s in it, and a Helper is defined entirely by the fact that something else needed it.

A utils file in particular is a place to put things you haven’t named, and it grows monotonically, and by year three it’s got a date formatter, a currency formatter, a debounce, something that talks to the API, and a regex nobody understands. The absence of a name meant there was no rule about what belonged.

I still write utils.js. I just now treat it as a to-do rather than a location.

Say what the business says

The single most useful thing I’ve picked up, and I got it from a project going badly rather than from a book.

Use the words the client uses for their own business. If the people who run the place call them jobs, they are jobs. Not tasks, not orders, not work items, not whatever the CMS’s admin happens to say. If the schools they sell to are “institutions” in the contract, they’re institutions in the code.

Two reasons, and the second is the one that surprised me.

The obvious one is that you can then have a conversation. When the client says “the job number should show on the invoice” and you have a thing called job with a number on it, the meeting and the code are the same shape and nobody translates. When you’ve called them tasks and they’ve got a reference, every conversation has a silent lookup step in it, and eventually somebody gets it wrong in a way that costs two weeks.

The less obvious one: adopting their vocabulary forces you to find out where their vocabulary is inconsistent, and it always is. On one project “customer” meant the company for the sales team and the individual buyer for the support team, and they had never noticed because they never had to be precise. Trying to name a database table surfaced a genuine ambiguity in how the business thought about itself, and that was worth more to them than the feature I was building.

One word per concept, and never a synonym

If I could keep one rule it’d be this one.

Pick a word for a concept, and use only that word, everywhere, forever. Never a synonym. Not for variety, not because a sentence reads better, not because the third-party API calls it something else.

The worst codebase I have ever inherited was not badly written. It was competent and tested and reasonably tidy. It just referred to the same entity as user, customer, client, member and account in different files, written by different people over four years, all meaning the identical row in the identical table. I lost about two days establishing that, and I was never fully confident, and I flinched at that code for the rest of the project.

Synonyms are how a codebase stops being readable. Not complexity, not cleverness. Two words for one thing, and now every reader has to hold a translation table in their head while they work.

Length is about distance

A small thing that removed a lot of low-grade arguing for me.

The right length of a name is proportional to how far it travels. i in a three-line loop is perfectly clear because everything you need is on screen. The same i held across 40 lines is not. A module-level export that other files import needs to be self-explanatory to somebody who has never opened the file it’s defined in, and that usually costs several words.

So n, el, i are fine in a tight scope and indefensible at the top level, and selectedProductQuantities is a reasonable export and unbearable inside a two-line map. Same code, different distance.

Rename early

Names get more expensive over time, and the curve is steep. Renaming something an hour after you wrote it is free. Renaming it after it’s in three files is a refactor. After it’s a column name, an API field, and a word the client now uses in meetings because they learned it from your admin screen, it’s a project.

So the moment you understand the thing better than you did when you named it, rename it right then, while it’s still cheap. That’s the whole discipline and I get it right maybe half the time.

Twenty minutes, well spent

I went looking for writing about this before I started, because it’s such a universal complaint, and there’s almost nothing. Six or seven posts, across the entire industry, on a thing every developer does 40 times a day and finds difficult.

I suspect it’s because there’s no tooling angle. Nothing to install, no library, no benchmark, no before-and-after graph. It’s just sitting there thinking about what a thing is, which produces no artifact except a slightly better word.

20 minutes though. I’d do it again.