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

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.

You might also like...

20

Oct.

Steve Hulet

Announcing Fresh Consulting’s WCAG 2.0 PHPCS Linter

Today, Fresh Consulting is announcing the release of our WCAG 2.0 PHPCS Linter. The linter is a set of rules (or sniffs) for PHP Code Sniffer which can automatically detect and alert when certain WCAG 2.0 violations are detected in code. WCAG 2.0 supports designers and developers in meeting the guidelines and success criteria of accessibility. The … Continued

17

Oct.

Sean Patterson

Dev Principle #11: DRY – Don’t Repeat Yourself

As the size and scope of a project increase, so does the complexity of the code base. One way to maintain and stabilize your code is to adhere to the “DRY” Principle: Don’t repeat yourself. #1: Use the DRY Principle to Decrease the Size of Your Code Base If you’re writing code to do the same … Continued

30

Aug.

Xavier Reyes

You Should Be Using BitBucket Pipelines

Commonly, developer workflows include pushing code to BitBucket. From there, you run processes like testing, updating a staging server, and generating documentation. All of these processes can become very repetitive. Thankfully, they can also be automated. That’s where Bitbucket Pipelines comes in. It’s simple – you only have to create a set of scripts that run … Continued