The Quote You've Seen a Thousand Times

"There are only two hard things in Computer Science: cache invalidation and naming things." — Phil Karlton (probably, attribution is also hard)

You've seen this on mugs. On conference slides. In every "funny dev quotes" listicle since 2009. And yet, the more code you read — and especially the more code you write — the more you realize this joke isn't really a joke. It's a diagnosis.

A Taxonomy of Bad Names We Have All Written

The Honest-But-Useless Name

Variables like data, info, result, temp, and stuff. These names are technically accurate and completely meaningless. data is always data. That's not the question. The question is what kind of data, where it came from, and what you plan to do with it.

The Aspirationally Clever Name

The function named processItems() that processes items but also filters them and sometimes sends an email. It was named before its scope expanded to eat three other responsibilities. Now it's a lie with a function signature.

The Abbreviation That Made Sense in Context

usr_cfg_mgr_svc. In the moment, with full context, this was perfectly clear. Six months later it is an archaeological artifact. Was it "user config manager service" or "user configuration migration script"? Both are plausible. Only one is correct.

The Boolean That Needed a Sentence

isEnabled, isActive, isReady. Enabled for what? Active in which context? Ready under what conditions? The boolean that seems obvious always becomes the boolean that requires a 20-minute Slack thread to interpret.

Why It's Actually Hard (Not Just Careless)

Bad names are rarely the result of developers not caring. They're the result of a fundamental tension: you have to name things before you fully understand them. You write the function, you make it work, and only later — through use, through bugs, through reading it at 11pm six months later — does its true nature reveal itself.

Good naming requires you to predict the future. How will this function grow? What will callers expect? What will confuse the next person? These are hard questions to answer before the code is even written.

A Few Rules That Actually Help

  • Functions should be named for what they return or do, not how they work. getUserById() is better than runDatabaseQueryForUser().
  • Booleans should complete a sentence. If you can't say "it is [name]" and have it make sense, rename it.
  • If you need a comment to explain the name, change the name. The name is the comment.
  • Rename ruthlessly during refactoring. The cost of renaming is low; the cost of confusion is high.

And when you still can't find the right name? // TODO: rename this when I figure out what it actually is is, genuinely, more honorable than a confident wrong name. At least it's honest.