Naming Things for AI

There's an old joke that the two hardest problems in computer science are cache invalidation, naming things, and off-by-one errors. The joke has survived because the naming part is true in a way the other two aren't — it's not technically hard, it's just persistently undervalued.

I've been thinking about naming differently since I started working with AI coding tools regularly. The stakes are higher than they used to be.

Names are the interface to intent

A function called getData tells you almost nothing. A function called getActiveBookingsForBarber tells you the domain, the filter, and the entity being returned. The implementation of both might be identical. The semantic surface is completely different.

For a human reading the code, this is a convenience. For an AI tool reading the code, it's the primary signal. LLMs don't run your code. They don't inspect types at runtime. They read identifiers, function names, variable names — and from those, they infer what your code is trying to do. A well-named codebase gives the AI accurate context. A poorly named one gives it noise.

The amplification problem

When you write code manually, bad names slow you down. You have to remember what temp2 is, reread the implementation every time you touch it, leave comments that drift from the reality. The cost is real but contained.

With AI tools, bad names compound. If your variable is called data, the AI will generate code that calls it data. If your function is called process, the AI will write more functions called process. The ambiguity propagates forward through every suggestion, every completion, every generated test.

I noticed this pattern clearly when using Claude Code on a codebase that had accumulated naming debt. The suggestions were coherent internally but meaningless in context — because the names I'd given things gave the AI nothing to anchor to. Cleaning up the names was the most effective thing I did before continuing.

Name it before you build it

The discipline I've landed on: name the function before I implement it. Not the parameters, not the return type — just the name. If I can't find a name that clearly describes what the function does, that's a signal the function isn't well-defined yet.

This was useful before AI tools. It's especially useful now, because a clear name is also a clear prompt. calculateRefundAmount(booking, policy) tells the AI exactly what to implement. handle(b, p) tells it nothing. The quality of AI-generated implementations scales directly with the quality of names you give them.

What a good name actually does

A good name makes a comment unnecessary. If the name requires a comment to explain it, the name is wrong. This isn't a style preference — it's a signal about how well you understand what you're building.

When I find myself reaching for a comment to explain a variable, I stop and rename it instead. // timestamp of last successful sync becomes lastSyncedAt. // user who created the booking becomes bookedBy. The comment disappears. The meaning stays, permanently attached to the thing it describes.

This also matters for AI-assisted code review. When I ask Claude Code to review a module, the quality of its feedback correlates with how clearly the code expresses intent. Vague names produce generic feedback. Precise names produce precise feedback.

Renaming is the best refactoring

One thing I've learned: renaming something is often the highest-leverage refactoring you can do. Not extracting functions, not reorganizing files — just finding the right name for something that's been misnamed.

When you rename something accurately, related code often becomes obviously wrong in ways it wasn't before. A function called saveUser that also sends a welcome email becomes a problem when you rename it correctly — because now the email send is clearly out of place. The rename didn't break anything. It revealed something.

AI tools make this easier. Rename a function, ask the AI to find all the places the old name assumption is baked in. The mechanical part is fast. The thinking part — finding the right name — is still yours.