Dev Principles

Development

Web Development

Dev Principle #1: Choose Appropriate Variable Names

June 9, 2016

Steven Rogers

By Steven Rogers

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.

[Blog] Covers 080616-01

Be Clear

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.

[Blog] Covers 080616-02

Be Concise

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.

[Blog] Covers 080616-03

Be Consistent

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.

If you are starting your own project, I would recommend looking at what other developers are using in that same language. Coding in Python? You should probably use snake_case. Javascript? CamelCase is your best bet. PHP? StackExchange has a great answer (they point out that different PHP frameworks deny or recommend specific cases).

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.

Conclusion

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.

Steven Rogers

Steven Rogers

Front-End/Full-Stack Developer

You might also like...

21

Aug.

Will Lingard

VR Developer’s Journal Part 1: Getting into VR

This is the first in a new series of Fresh blog posts about Virtual Reality (VR). Eventually we’ll be diving into the more technical aspects of software development for VR; however, this first blog post is more of an introduction, to give you some background and better context to what follows. It’s important to note … Continued

26

Jun.

Travis Luong

How to Debug Django Apps

How to Debug Django Apps In the JavaScript world, my primary debugging workflow consists of dropping a debugger or a console.log into the code and seeing what happens in the browser’s developer console. This methodology has always worked effectively for me. However, I have started to work more with Python and Django recently, and though … Continued

25

May.

Sean McKay

Adventures in Optimizing Performance

Even if a programmer is very comfortable with their codebase and their technology, they won’t always be correct in determining what portions of the program are running slow. To that end, the first step for optimization with an existing system is profiling or measuring the code base. This ensures that the critical parts slowing down … Continued

Pacific Science Center

application maintenance and development

Pacific Science Center

Cisco

mobile development

Cisco

Deloitte

web design, microsite development

Deloitte

Seattle Public Library

ui/ux design, microsite development

Seattle Public Library