Article summary
Well-named variables are one of the most useful tools for building a maintainable and predictable codebase. Poor variable names can confuse users, but good ones make code seem effortless. As Ward Cunningham put it:
You know you are working on clean code when each routine turns out to be pretty much what you expected.
Naming variables well is one of the first and most important things you can do to create code that feels expected.
Variable names should have different levels of complexity. Some only contain a simple concept, or carry the concept a short distance. These should be given short, simple names. Others carry much more complexity or have a larger scope. These deserve clearly thought-out, more detailed names.
Of course, there’s no such thing as a perfect name. Sometimes, you have to settle for picking something good and move on; most code can be read and understood with enough time.
With that in mind, I’d like to share a few things I’ve found valuable to think about when naming variables.
Names to Avoid
It’s almost always best to avoid single-letter variable names, which are not unique enough to help the reader associate a meaning with the name. This increases the mental tax on the reader and makes it harder to understand what the program is doing. (Idiomatic variables are an exception which I’ll cover shortly.)
If you need to place a comment next to the instantiation of a variable, you’ve probably named the variable poorly. Many of these “what” style comments can be pulled into the name of the variable to avoid a separation of meaning. Here’s a quick example of pulling a “what” comment into a variable name:
address = 123.123.123.123 // this holds the server's ip address
serverIpAddress = 123.123.123.123
Repeating the type of the variable in the name inevitably clutters the meaning of the variable. A specific enough variable name will suggest the type to the user, and many modern editors and workflows will deduce the variable types for the user. An example of this is itemList vs.items.
Some variables just don’t need to exist at all. They serve to clutter the reader’s mind and increase the amount of noise that needs to be deciphered. An example of this would be a variable that gets declared to be used one line later, and never used again.
There are also many common names that almost never carry meaning, including favorites like temp, var, and results. These variables often have more meaning that isn’t being properly expressed, similar to single-letter variables.
A Better Approach
In some cases, adding variables can clarify the meaning. A prime candidate for this is when you’re introducing constants, which often take an ambiguous string or number and emphasize or contextualize the meaning of the value. Good examples of this include PROCESSING_MODE = ‘processing_mode’ or lines_per_page = 50.
As I touched on earlier, there are a few short variable names that are very idiomatic, and should be considered exceptions to the rule. Examples include things like i for a loop index, x and y for coordinates, and e for exceptions/errors.
In my experience, the best rule of thumb for naming variables is to name them “teutonically.” Many Germanic languages create new words by stringing existing words together. One example is the word “zahnfleisch” or “tooth flesh”. Our equivalent word is “gums.” Variables named in this way help minimize using domain language that might confuse the reader, while reducing the complexity of the name. Be careful with overly long names, though, since they can be harder to parse when reading the code.
I hope these ideas help you come up with better variable names and make your code reviews more enjoyable. The value of well-named variables is subtle, but important once you realize what it can do.