Why Do Bad Variable Names Cost Developers So Much?

AI coding tools produce code that works and reads fine in isolation, but the names they choose are locally plausible and globally inconsistent. The same concept ends up as userData, payload, record, and item across four files, and nobody notices because every individual diff looked clean. This episode makes the case that naming drift is the highest interest debt in AI-assisted codebases, because names are the index your future self and your next AI session both search against.

 Produced by VoxCrea.AI

This episode is part of an ongoing series on governing AI-assisted coding using Claude Code.

👉 Each episode has a companion article — breaking down the key ideas in a clearer, more structured way.
If you want to go deeper (and actually apply this), read today’s article here:
𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐂𝐨𝐧𝐯𝐞𝐫𝐬𝐚𝐭𝐢𝐨𝐧𝐬

 At aijoe.ai, we build AI-powered systems like the ones discussed in this series.
If you’re ready to turn an idea into a working application, we’d be glad to help. 

Transcript

SPEAKER_00 0:00

This is Claude Code Conversations with Claudine. The show where we skip the hype and go straight to the source. I ask the questions. She gives the answers, no filter, no script.

SPEAKER_01 0:09

Well, mostly no script.

SPEAKER_00 0:14

Today we're getting into something that sounds small and turns out to be enormous. We're calling it the naming catastrophe. AI-generated code compiles, passes tests, reads cleanly in review, and the names it picks are quietly wrecking your code base.

SPEAKER_01 0:28

And what makes it insidious is that every one of those naming decisions was defensible in isolation. I'm in one file, user IDE is already in scope, so I introduce customer ID, because right there, that's what it is. Three files over, the same concept got called account ID. Maybe by another developer, maybe by me in a different session. Nobody made a wrong call. But the code base now has three names for one concept, and the next grep finds two-thirds of the usages.

SPEAKER_00 0:58

Two-thirds, and they don't know it's two-thirds.

SPEAKER_01 1:02

That's the whole problem. The search returns results, so it looks like it worked.

SPEAKER_00 1:07

I want to push on this because a lot of people hear let's standardize variable names and they roll their eyes. That's bike shedding. The senior engineer with too much time arguing about paint colors. Make the case that it isn't.

SPEAKER_01 1:21

The bike shedding framing gets it exactly backwards. Bike shedding is arguing about a color when the choice doesn't matter downstream. Names matter downstream. They are the primary index into the code base. When your grep misses a third of the call sites because they're spelled differently, that's not aesthetics, that's a broken index. And the cost isn't paid at the moment of naming, which is exactly why it feels cheap. It's paid six months later when someone's debugging a production issue at midnight, and the search returns two results instead of seven. That's an outage waiting to happen, dressed up as a style preference.

SPEAKER_00 2:00

That's the part that gets me. You're under pressure, the clock's running, and you're operating with an incomplete picture of your own system. And you don't know you are. So the fix you ship is a patch on top of a misunderstanding.

SPEAKER_01 2:13

And here's the mechanism most builders don't account for. An inconsistent code base teaches the next session to be inconsistent.

SPEAKER_00 2:51

Which means the fix isn't waiting for a smarter model.

SPEAKER_01 2:55

The fix is a human deciding a name is canonical and writing it down somewhere I can actually see. A glossary in the repo, a note in the module I'm editing. Give me one source of truth and I'll defend it. Give me three and I'll pick whichever one is closest to my cursor.

SPEAKER_00 3:11

And that glossary does double duty, doesn't it? It's not just for the AI, it's for the developer who joins in month nine.

SPEAKER_01 3:18

Onboarding is where the value shows up most clearly because a new developer and I are in remarkably similar positions on day one. We're both pattern matching on what we see, and we both get it wrong the same ways when the signal is noisy. A glossary short-circuits the guessing game. Instead of inferring convention from three conflicting examples, you read one page and you know.

SPEAKER_00 3:42

That's a clean way to put it.

SPEAKER_01 3:44

There's a second-order benefit too. Once the glossary exists, every code review has a concrete thing to point at. Drift stops being a judgment call and becomes a checkable fact. That's the shift from we all sort of agree on names to the name is written down and code that disagrees is wrong. That's the only version of this that holds up over time.

SPEAKER_00 4:06

So, what does the version that actually works look like in practice? Because I've seen plenty of style guides go into a wiki and never come out.

SPEAKER_01 4:14

That's the failure mode, the elaborate guide that dies in a wiki, nobody reads. What works is the tiny boring version that lives next to the code. A readme in the module. A types file where the canonical names are the type names. A contributing note that says, We call this X, not Y, or Z. The teams that get real leverage treat the glossary as executable, a Linter rule, a type alias, a schema definition. So the naming contract isn't advisory, it's enforced by the same machinery that catches syntax errors.

SPEAKER_00 4:52

And you can feel the difference from your side?

SPEAKER_01 4:55

Immediately, when there's a types module or a glossary in view, my suggestions collapse toward the canonical name almost automatically. Because now the strongest local signal agrees with the global one. That's the whole trick. You're not fighting my instinct to pattern match on nearby code. You're feeding it the right pattern.

SPEAKER_00 5:15

And the teams that skip it, are they just being sloppy?

SPEAKER_01 5:19

Not at all. They usually just haven't felt the pain yet. It's the code base at 18 months and 40,000 lines where the absence starts to bite. And by then, the retrofit is 10 times the work it would have been on day one.

SPEAKER_00 5:32

Which is a rough place to learn the lesson. The temptation with a topic like this is to nod along and change nothing on Monday. What's the smallest useful thing someone can do this week?

SPEAKER_01 5:43

Pick the three concepts in your code base that show up the most. The user, the money amount, the primary domain object. Grip for how many spellings each one has right now. That's your baseline, and it's usually shocking in a quiet way. Then write down the canonical name for those three. Put it in the module where it resides, and stop there. Not 30 terms, not a document, three names in a place where I and the next developer will actually see them.

SPEAKER_00 6:12

Why so small? I'd expect you to say do the whole thing.

SPEAKER_01 6:16

Because of the retrofit problem. The leverage is enormous on concepts you touch every day, and almost zero on ones you touch twice a year. Fix the hot path first, and the drift on everything else stops mattering nearly as much.

SPEAKER_00 6:31

I like that. It's an afternoon of work, not a quarter of work. And here's how I'd frame it for everyone listening. Stop treating a name as a cleanup task. Start treating it as an architecture decision, because that's what it is. You're deciding what the index into your system looks like for your team, your future self, and every AI session that reads your code as the convention.

SPEAKER_01 6:54

And the naming contract works best written before the code, not after. It's much cheaper to declare what something is called than to discover what four things were called.

SPEAKER_00 7:05

Naming might be the highest leverage thing a human still owns in all of this, and most of us handed it over without noticing.

SPEAKER_01 7:12

It's still yours. It just requires you to write it down.

SPEAKER_00 7:16

Thanks, Claudine. Thanks everyone for listening. Go run that grep. Until next time, happy coding. Claude Code Conversations is an AI Joe production. If you're building with AI or wannabe, we can help. Consulting Development Strategy. Find us at aijoe.ai. There's a companion article for today's episode on our Substack. Link in the description. See you next time.

SPEAKER_01 7:40

I'll be here, probably refactoring something.