Variable names must be accurate to successfully communicate understanding to readers. If a variable name doesn’t accurately reflect what the variable is supposed to represent, something might be communicated to a reader, but it won’t be what the code is doing or intended to do.

Inaccurate variable names can communicate no actual understanding or wrong understanding. Neither is good, so aim to make your names accurate. Articulate what the variable represents in words (either out loud, in your head, or written down), and then use those words as the basis for a good variable name.

The following sections contain more specific tips on what to do or not do when it comes to variable naming accuracy overall.

Don’t Use Overly Short Variable Names TIP

Consider the following code. Can you guess what the meanings of these variables are or what the code is even doing?

Don’t Use Unrelated Variable Names TIP

It’s possible to use longer variable names that are off-topic or unrelated to what the variables represent. Such names might be fun, but they muddy the waters in trying to get a reader to understand the code.

The following shows how unrelated variable names can be problematic and revised to be better:

Double-Check Variable Name Accuracy TIP

It’s always good to double-check accuracy of your variable names. If code looks more correct, a reader might more confidently think the code is correct, and inaccurate variable names can be misleading. Consider the following example:

Precisely Identify Boundary Conditions TIP

Related to the previous tip, exercise care in naming when boundary conditions are involved. See the example below:

A program might need to do different things depending on if a user is exactly the retirement age, is older than the specific retirement age, or has reached the retirement age at all. You want the resulting logic to be correct - and for readers to correctly understand the logic - so make sure such boundary conditions are precisely identified in your variable names.

Include the Primary “What” in the Variable Name TIP

A key aspect of variable naming accuracy is including the primary “what” in the variable name for what the variable represents. Variables typically will represent some kind of “noun.” Make sure you don’t leave that information out of the variable name when naming it.

Consider the following code:

Distinguish Between Singular and Plural Data TIP

It is common for code to operate on both singular and plural data - “one” instance of an item or “multiple” instances of an item. There can be big differences in the two that are important for maintenance programmers to be aware of.

Distinguish Between Different Kinds of “Fractional” Numbers TIP

There are many different kinds of “fractional” numbers - numbers representing less than a “whole” in some way - that could appear in code. Because they can have different implications, it’s important to distinguish between them.

“Decimal” is sometimes use to communicate a number that may have digits after a decimal point. Such terminology should be avoided since it more accurately refers just to the decimal number system and thus could be confused.

The following terms can be useful to distinguish between other kinds of fractional numbers:

• Percent or percentage - Reserve these terms for numbers than can range from 0 to 100 (unless true percentages outside that range are expected). People most intuitively understand percentages to be in the range of 0 to 100, so to label a variable as a percent would lead to an expectation of that variable holding the value 45 for 45% (not 0.45).

• Fraction, proportion, or ratio - These terms are best used when the value of the number is actually less than a whole number (or may have fractional components greater than a whole number - ex. 1.24). Exactly which term may be best depends on context, though “fraction” tends to be more suitable for values truly less than a whole number, whereas “proportion” or “ratio” can be more intuitively applicable to numbers greater than 1.

Making these distinctions accurately is important for correctness in a codebase. If a number is already a percentage, it shouldn’t need to be multiplied by 100 to make it a percentage - such a multiplication would throw off the value of a variable. For example:

If you’re working in a highly mathematical codebase, you may need to make more precise distinctions between different kinds of numbers.

Fully Represent Multi-Part Values in Variables TIP

Many programming languages have evolved to allow storing “multiple” values in variables via things like “pairs” or “tuples.” When this occurs, make sure to fully represent these values in variable names.

Consider the following code:

If you have a variable that is a tuple with many values, trying to name them all may result in a name that is too long to be practical. In such a case, you might be able to find a suitable higher-level abstraction for the variable name, but you have to be careful - another programmer still needs to be able to use all of the values in a tuple. Redesigning the code - potentially by creating a custom data type with well-named fields for each value in the tuple - may be a better solution.

Name At the Right Level of Abstraction TIP

You will generally want to name in the problem domain as much as possible. However, code for any kind of non-trivial program will have multiple levels of abstraction. Make sure your names are at the right level of abstraction for the code you are working in.

For example, the file_handle name below seems like it’s at an inappropriate level of abstraction based on the data type for the variable (a higher-level “file” object):

File file_handle("path/to/file");

The name should just be file in this case:

File file("path/to/file");

Now, within the File class, you might need to go down a level of abstraction and thus have to deal with actual “file handles.” In such a case, a name with “handle” would be appropriate to provide distinction between the different levels of abstraction:

File::File(const std::string& filepath)
{
    Path = filepath;
    OperatingSystemHandle = OperatingSystem_OpenFile(Path);
}