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.
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 effort on the reader and makes it harder to understand what the program is doing.
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 = 18.104.22.168 // this holds the server's ip address serverIpAddress = 22.214.171.124
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
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.
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,
y for coordinates, and
e for exceptions/errors.
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.