Dev Principle #1: Choose Appropriate Variable Names
Variables are the dynamic heart of programming. Variables make code more than a static set of instructions. They allow logic to occur, enabling developers to measure time, analyze data, and customize the program to the user.
Variables are so important to the code that they deserve a good name that accurately describes their purpose. Sometimes a bad name can be the difference between a fellow developer understanding what everything does at first glance and not having any clue where to begin.
It’s likely that we’ve all been there. Trying hard to come up with an accurate, concise variable name is a challenge. What’s the best approach to naming a variable that is so obscure, complex, or overused that no single name under 32 characters could explain exactly what it is? If you need a variable for a simple, single line in your code, could you come up with something better than just “X”?
The fact is that variable names matter, so much so that we’ve decided to elaborate on a few tips to help you come up with clear, concise, and consistent variable names.
A good number of programmers will sacrifice clarity for speed. But it’s important to consider that cutting a truly accurate variable name in favor of a handful of keystrokes could be construed as bad programming.
In 201 Principles of Software Development, Alan Davis writes:
“Some programmers insist on naming variables with names like N_FLT, or worse, like F. The usual argument is that it makes programmers more productive because of the reduced key presses. Good programmers should spend a very small percentage of their time typing (maybe 10 to 15 percent); most time should be spent thinking. [But] how much time is really being saved?”
In many cases, a few extra keystrokes make a variable clearer. Ultimately, a few more seconds of typing reduces the cognitive load put on other developers to figure out a variable’s meaning and purpose. When creating a variable for a range of dates, calling it “dRange” is a lot less clear than calling it “dateRange.”
We recommend avoiding short or ambiguous variable names such as “tmp,” “x,” or “i” whenever possible. It’s easy to go down this path, but in the long run, having a variable name that explains what the variable is doing is important. Even if the variable is only being used in two lines or it is just an index in a “for loop,” it is much more useful to have a name that explains itself at a glance.
It’s important to consider if your variable names will be understood globally. Fresh has offices in Europe and Asia – will the same abbreviations we use in the US be understandable to developers overseas? Given that some of our bigger projects involve international collaborations, the clarity of variable names becomes even more important.
A great way to test if your variable names are clear is to fit them into this sentence:
“This is the _____.”
For example, saying “This is the dRange” doesn’t convey enough information about what the variable is. When you try “This is the dateRange,” you immediately know what this variable is.
However, in some cases abbreviations are useful. The infamous fibonacci sequence recursive function is commonly shortened from “fibonacci()” to “fib().” Just be sure that the abbreviation is explained in the comments.
Another thing to note to keep variable naming clear is the amount of comments needed. A large comment or lots of comments for a variable is usually a red flag that it was not named properly. Some would argue that “good code doesn’t need comments.” Comments do have their place in code, but explaining in-depth what a badly named variable does should not be one of them.
Avoid excessively long variable names. If you have a variable that stores a user’s favorite color on the object named “user,” you might not want to call that variable “ThisPersonsFavoriteColor.”
Instead, consider the shortest way you can get the information across clearly. Maybe call this variable “favoriteColor,” so when you access the variable like “user.favoriteColor” even people who aren’t computer savvy know exactly what you are talking about.
You could also use the “name test” in the previous section to say “This is the user.favoriteColor” – and it still makes a reasonable amount of sense.
As stated previously, take caution when using abbreviations. In some cases abbreviations can be a cause for confusion, but in other cases they keep the line length short and make the code look cleaner overall.
A case could be made for this being the most important rule. It doesn’t matter if you use PascalCase, camelCase, snake_case, lowercase, or hyphen-case with or without naming conventions like Hungarian Notation. It is very important to stay consistent with the naming conventions the project is currently using.
Hungarian Notation also has its own place, given that it is used properly. Consider reading Joel Spolsky’s article “Making Wrong Code Look Wrong.” Spolsky explains the way Hungarian Notation was meant to be used rather than the way you might find it being used today.
Variables are a central component of programming and they need to be taken seriously. By coming up with clear, concise, and consistent variable names, you can make communication between yourself and developers more efficient, and your code labels easier to interpret and understand.