Improve your Code by Writing Better Variable Names

By: Amy M Haddad

“You should improve your variable names,” a programmer told me bluntly after reviewing a program of mine. His comment stopped me in my tracks. The writer in me thought I should have naming down. But I didn’t. It’s still something I’m working on.

His comment got me thinking how I could do things better. In fact, I think many of us could name variables better. Anyone who’s been stuck trying to decipher a program knows what I’m talking about.

And that’s what this post is about: how to write better variable names. It’s something that programmers often neglect for other “more important” things. But variable names matter—a lot.

What I’m finding is this: if you want to improve your code, improve your variable names. Here are three ideas to try.

1. Make a checklist

I have a “variable name” checklist. It hangs on the wall to the left of my computer monitor.

It’s hard to forget about a checklist when it’s in your line of vision. That’s why I rely on a physical copy, not a file on my computer. Now writing clear, meaningful variable names top of mind—no excuses.

At the top of my checklist contains a naming gem:

“State in words what the variable represents. Often that statement itself is the best variable name.”

I have Steve McConnell’s book, Code Complete, to thank for that bit of advice. The key here is nailing down the what. Now I constantly ask myself: “what does this variable represent?” And, to McConnell’s point, the answer is in fact usually “the best variable name.”

My checklist also includes these important points when thinking about naming:

• Be clear. Is your variable referring to one pizza or many pizzas?
• Be specific. Is employee better than person?
• Be meaningful. Will c make sense to someone else reading your code? Or is customer better?

There’s more advice from McConnell’s book worth mentioning: use positive variable names for booleans. “Negative names like notFound...are difficult to read when they are negated—for example, if not notFound” (emphasis mine). That’s hard to read and understand.

2. Read your code out loud

As a writer, the last step in my writing process is to read my article out loud to myself. It’s something I’ve started to do as a programmer, too.

If it sounds awkward, wordy, or unclear, it probably is. This is a very simple step that’ll catch errors, opportunities for refactoring, and naming.

3. Get feedback

Awareness can be a great teacher, which is how I came to learn that I needed to work on my own variable naming. It’s easy to assume that our thinking is clear to others. Don’t assume; find out for yourself.

Ask another programmer to read your code and provide feedback. Simply ask: "is my code easy to read?" If not, have them point out why and where they’re getting hung up.

“You shouldn’t need to figure out code,” explains McConnell. “You should be able to read it.”

And that brings us to the larger point. You know you’re reading a well-written book when reading is effortless. The same is true for reading code: aim for effortless reading. Naming variables properly is a critical step in that process.