Introduction

Have you ever tried to read code? And by “read code”, what I really mean is “read and understand code.” Just being able to articulate what some letters or words are isn’t useful if you don’t understand what they mean when put together.

Computer code originally started out as sequences of bits - combinations of 0s and 1s. While those binary numbers are a necessary abstract representation of electrical states in computer hardware, such machine language is not easily readable by humans - sequences of 0s and 1s don’t typically have inherent meaning to humans, and trying to parse and lookup meanings behind such sequences is mentally taxing.

Over time assembly languages were developed to give some short, more readable names to computer instructions. An instruction like ADD EAX, EBX is much easier for humans to read than a seemingly arbitrary combination of 0s and 1s.

Assembly languages can still often be cryptic and hard to read, at least for humans trying to solve complex problems in the real world. Thus, higher level programming constructs and languages were introduced over time to make it easier for humans to program computers.

A fundamental construct in most programming languages is the variable, a way to label locations in memory that hold values with names of our choosing. Just as we assign words in human languages to real things to make them easier to talk about, assigning names to values in a computer’s memory makes it easier to discuss and understand computer programs.

Given how prevalent variables are and their impact on human maintainability of modern computer code, naming variables well is important. Historically, many code examples haven’t had the best variable names. But there are many simple, yet powerful, techniques that you can start applying immediately to variable naming that can dramatically improve the quality of life for both yourself and your fellow programmers.

This training will cover these techniques so you can master the craft of variable naming, making your code easier and more delightful to read. While this training will primarily focus on naming variables, many principles are applicable to other coding constructs to which we assign names.

Variable Naming is About Understanding

As previously mentioned, computers store and process values as sequences of binary 0s and 1s. Whatever code you write as a human ultimately gets translated to these binary numbers. The computer doesn’t care what names you assign to these values.

But your fellow humans will care.

Code is typically written once and read many times. It’s read as you initially double-check and debug it before committing it to your codebase. It’s read as fellow programmers try to understand it or fix bugs. It’s read when future enhancements are made.

Code has two audiences - the computer and the human. Writing code that is simple and efficient for a computer to execute is an important skill, but compilers will translate whatever code you write to the machine code needed for the computer to do what you specified. Variables don’t really exist in computer hardware though, so they’re effectively erased during this process. Variables exist in programming languages for communicating to human audiences. So whenever looking at a variable name, always ask: “What is this communicating to others?”

Computer code can be complicated - after all, we’re typically trying to span numerous levels of abstraction trying to get a computer that only understands simple binary instructions to solve some complex problem in our real human world. For that to be done correctly, humans need to understand what the code is doing - and is trying to do. Thus, you want variable names to assist in communicating understanding to you and your fellow programmers.

Good variable names have benefits that can extend just beyond a programming team. In well-written code with good variable names, non-programmers (testers, customer support, project management, business staff, etc.) may be able to read the code and glean understanding, inviting further collaboration with others involved in bringing a great software product into the world.

Clear vs. Unclear Names

To close out this section, the following are just a few examples of clearer names versus unclear names:

The above is a starting point to show how much difference can exist between common poor variable names and better names. We’ll cover why some of the clearer names are better as we go through the training. And there are multiple ways some of these names could be improved, which we’ll cover in future sections as well (hint = longer names above tend to communicate additional understanding).