Dev Principles

Development

Web Development

Dev Principle #1: Choose Appropriate Variable Names

June 9, 2016

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

Front-End/Full-Stack Developer

Enthusiastic Full-Stack Web Developer. Hobbyist in arts, travel, and games both tabletop and electronic. I hand-sculpt websites from the back-end core processes to the front-end user experience.

Unless otherwise specified, source code in this post is licensed under a
Creative Commons Attribution 4.0 International license (CC BY 4.0).

You might also like...

12

May.

Should I Use RxJS in My Project?

If you’re thinking about using RxJS, you might as well be asking, “Should I use a jump kick in a street fight?” Unless you are Bruce Lee, probably not. As a disclaimer, I am not an RxJS pro. I only started learning about it a couple of weeks ago. Consider this post a record of … Continued

6

Apr.

Testing Methods: End-to-End Testing

What Is It? Testing flows from “end-to-end.” For a website, this might mean from placing an order, to checking out, to returning an item. End-to-end testing is focused on mimicking “real life” use cases. End-to-end testing increases confidence in the stability of the app or product, but it can be difficult to quantify each “end,” … Continued

21

Mar.

Testing Methods: Client/User Acceptance Testing (UAT)

What Is It? Users (clients) test the software to ensure it can handle the required tasks associated with “real-world” scenarios. User acceptance testing (UAT) is performed to check if the software conforms to the business’s needs and to the product requirements. UAT validates assumptions and quantifies personas, but it can be difficult to structure a … Continued