Naming Things in Programming: Why It's So Hard (and How to Get Better)

TL;DR: Naming things is hard because a good name forces you to understand exactly what a piece of code does—and most of us don't have that clarity until we've written it. The fix isn't cleverness, it's honesty: name the thing for what it does, change it the moment it stops being true, and stop treating renaming as a chore.

You've been staring at a blank line for four minutes. The function is done. It works. All that's left is the name, and your brain has chosen this exact moment to go completely blank. So you type processData and move on, hating yourself a little.

Every programmer has lived this. Phil Karlton famously called naming things one of the two hard problems in computer science (the other being cache invalidation, and off-by-one errors). The good news: it's a skill, not a curse.

Why naming things in programming trips up everyone

A bad name is usually a symptom, not the disease. When you can't name a function, it's often because the function does three things and you're trying to describe all of them in one word. That's a design smell wearing a naming costume.

The other trap is vagueness by committee. Names like data, info, manager, util, and handle feel safe because they're never technically wrong. They're also never useful. I'd rather see retryFailedPayments than processItems any day of the week.

Here's the test that actually works: read the name out loud in a sentence. "Call calculateShippingCost." If that sounds like something a human would say, you're close.

So how do you name variables, functions, and classes?

Each one has a different job, and the names should show it.

• Booleans read like yes/no questions: isActive, hasPermission, shouldRetry.
• Functions start with a verb: sendEmail, parseConfig, findUserById.
• Classes name the thing, not the action: Invoice, RateLimiter, ConnectionPool.
• Variables describe the value's role, not its type: userCount beats num beats int1.

The consistent thread is specificity. getUserById(id) tells you what it needs and what it returns. getUser(id, true) does not, and future-you will curse present-you for it.

What about naming conventions and consistency?

Follow the convention of the codebase you're in, full stop. Python's snake_case and Java's camelCase aren't opinions worth fighting over when the file next to yours already picked one.

Two rules I'd defend with my life:

1. Be consistent over clever. If the codebase says fetch, don't introduce retrieve for the same operation—it makes readers wonder if there's a difference.
2. Avoid misleading abbreviations. cnt saves two keystrokes and costs everyone a micro-pause. usr is fine. x is not.

One more: don't encode the type in the name. userList becomes a lie the day it's a Set. Name the concept, not the container.

FAQ

How do you name a variable that holds multiple things? Use a plural or a collective noun: pendingOrders, activeSessions. Skip suffixes like List or Array—they describe the structure, not the meaning.

Should I rename things even if the code works? Yes. Renaming is cheap, and reading bad names is expensive. In modern IDEs it's a keyboard shortcut, not a project. Ship the rename with the next commit.

What do I do when I just can't think of a name? Write the name as a full sentence in a comment first. "Gets the user's preferred currency from their last order." The concise name usually falls out of that sentence on the second read.

Key Takeaways

• Naming is hard because it forces clarity—if you can't name it, you don't understand it yet.
• Describe what a thing does or is, not how it's built or what type it holds.
• Vague names like data and manager are a design smell, not a shortcut.
• Rename freely. Bad names compound interest; a good rename costs five minutes.