Variable Naming in Programming – Code Complete

Variable Naming in Programming – Code Complete

Variable naming is one of the most uncertain topics in programming. There are not any definite rules for naming a variable. In the book “Code Complete” there is a section about it. This section describes very good practices on this topic. Thus, this steers developers in a very good way. Let’s learn what is described in this section. This post will provide a very good motivation for naming the variables precisely.

Choose the variable names with care

While choosing a name for a variable, do not be emotional. You are not choosing a name for your pet. A good variable is an understandable variable. In a nutshell, a good name for a variable describes well “what is the problem” in the business of the related context.

A bad naming sample

1
2
3
4
x = x - xx;
xxx = fido + salesTax(fido);
x = x + lateFee(x1, x) + xxx;
x = interest(x1, x);

Here, what is x? Or, what is xxx? What does x1 stand for? What will happen if I change xx?

A good naming sample

1
2
3
4
balance = balance - lastPayment;
monthlyTotal = newPurchases + salesTax(newPurchases);
balance = balance + lateFee(customerId, balance) + monthlyTotal;
balance = balance + interest(customerId, balance);

It’s more readable, memorable and understandable.

The Most Important Naming Consideration

The most important consideration in naming a variable is that the name fully and accurately describes the entity the variable represents. Comparatively, the easiest technique is to state in words what the variable represents. In that way, it is easy to read and it is unambiguous.

Samples

  1. For a variable that represents the number of people on the US Olympic team: numberOfPeopleOnTheUsOlympicTeam
  2. The number of seats in a stadium: numberOfSeatsInTheStadium
  3. The maximum number of points scored by a countries team in any modern Olympics: maximumNumberOfPointsInModernOlympics
  4. The current interest rate: interestRate

As it can be seen above, some variable names may seem a little bit long but we will cover that topic later.

Examples of Good and Bad Variable Names

Purpose of Variable – Good name – Bad name

The velocity of a bullet trainvelocity, trainVelocity, velocityInMph – velt, v, tv, x, train
The current datecurrentDate, todaysDate – cd, current, c, x, date
The lines per pagelinesPerPage – lpp, lines, l, x

Problem Orientation

A good variable name should describe the problem rather than the solution. And, it must describe the “what” rather than the “how”. In general, you can ask the question “what is the problem” while naming a variable. You can name the variable easily according to the answer to the question.

To represent a record of employee data, you can use the names either inputRec or employeeData. inputRec is more likely to tell how the problem is handled, this is bad. employeeData describes the “what”, this is good. Similarly, for a bit field indicating status, bitFlag describes how the problem is solved but printerReady describes what the current problem is.

Optimum Name Length

The optimum name length must be between x and maximumNumberOfPointsInModernOlympic. The problem with x1 and x2 is, you can discover what x is but you cannot know what is the relation between the x1 and x2. In the same time, names that are too long are hard to type and manage.

The optimum length for variables is between 8 and 20. But, it doesn’t mean that you should force all of the variables into this rule. It means that when you check your program if your variables seem too short than check the meanings if descriptive. In the same way, if they seem very long check that if you can make them shorter for the ease of maintenance of your code.

Samples

Too long names: numberOfPeopleOnTheUsOlympicTeam, numberOfSeatsInTheStadium, maximumNumberOfPointsInModernOlympics
Too short names: np, ns, mp
Just right names: numTeamMembers or teamMemberCount, seatCount or numSetasInStadium, teamPointsMax or pointsRecord

The Effect of Scope on Variable Names

Above, we have mentioned that variable names must not be very short or very long. But, there are exceptions to these rules. For example, as many developers are using it this way, loop counter variables are used as i or j or k.

The rule is, if a variable’s scope is small like loops, using the name as i is suitable. When the scope is getting bigger, the variable must have a meaningful name (for example global variables).


1
2
3
for(int i = 0; i < 5; i++) {
    System.out.println("This text is printed for five times");
}

But, if you use the loop variable in another place outside of the loop, it is better to give it a definitive name.


1
2
3
4
5
6
7
int recordCount = 0;
while (moreScored()) {
    score[recordCount] = getNextSocre();
    recordCount++;
}

//code that uses recordCount..

Also, If you have nested loops and accessing an arrays cells, it is again better to use definitive names for the loop indexes. Thus, you won’t type i and j or k accidentally in wrong places.


1
2
3
4
5
for(int rowIndex = 0; rowIndex < 5; rowIndex++) {
    for(int columnIndex = 0; columnIndex < 5; columnIndex++) {
        System.out.println(customerNames[rowIndex][columnIndex]);
    }
}

Use Qualifiers on Names That Are In the Global Namespace

When you have global variables, you must use long descriptive names. You can use prefixes to divide them into qualifiers. So that their names will be shorter and they can be meaningful.

Instead of the below namings:

1
2
3
4
USER_INTERFACE_SUBSYSTEM_CUSTOMER_NAME_LABEL
USER_INTERFACE_SUBSYSTEM_CUSTOMER_LASTNAME_LABEL
DATABSE_SUBSYSTEM_CUSTOMER_NAME_LABEL
DATABSE_SUBSYSTEM_CUSTOMER_LASTNAME_LABEL

You can name them like these:

1
2
3
4
UI_CUSTOMER_NAME_LABEL
UI_CUSTOMER_LASTNAME_LABEL
DB_CUSTOMER_NAME_LABEL
DB_CUSTOMER_LASTNAME_LABEL

Computed-Value Qualifiers in Variable Names

Computed value qualifiers are variables like totals, averages, maximums and so on. If you modify a name with a qualifier like Max, Min, Sum, Total, String or Pointer, put the qualifier word at the end. This will provide:

  1. The most significant part of the variable will be in the first place. This will provide high readability. Thus, the meaning will be easily understandable.
  2. This will avoid the confusion like if you use both variables totalRevenue and revenueTotal. They may seem same but this naming convention will describe what they are exactly.
  3. The names like revenueTotal, expenseTotal, revenueAverage and expenseAverage have a pleasing symmetry.
  4. The consistency improves readability and eases maintenance.

In the meanwhile, an exception to this rule is when you use variables like numCustomers and customerNum. While numCustomers describes the number of customers, the customerNum describes the identifier of a customer. To overcome this, you can use names like customerTotal and customerIndex.

Common Opposites in Variable Names

While coding, using naming conventions for opposites helps consistency which helps readability. For example, pairs like begin/end are easy to understand and remember. You can find a list of opposites below.

  • begin/end
  • first/last
  • locked/unlocked
  • min/max
  • next/previous
  • old/new
  • open/closed
  • visible/invisible
  • source/target
  • source/destination
  • up/down

Naming Specific Types of Data

In addition to the naming considerations, this section describes rules for loop variables, status variables, temporary variables, boolean variables, enumerated types, and named constants.

Naming Loop Indexes

We have covered this topic at “The Effect of Scope on Variable Names”.

Naming Status Variables

At every time, think of a better name than “flag” for status variables. Because it doesn’t give you any clue about the context. For clarity, flags should be assigned values and their values should be tested with enumerated types, named constants, or global variables that act as named constants.

Statements like “statusFlag = 0x80;” don’t give any clue what statusFlag is used for or what is the value “0x80” stands for. Instead of this, the statement can be written like “characterType = CONTROL_CHARACTER”. Here, we know that the variable characterType holds the value for the type of the used character and currently the character is the control character.

Naming Temporary Variables

In general, temporary variables hold the intermediate calculations and housekeeping values. Thus, the names are generally used as temp, x or t. At the same time, temporary variables indicate that the developer doesn’t understand the context clearly. On the other hand it’s often necessary to preserve values temporarily but in reality, almost all of the variables are temporary. Calling a few of them temporary indicates that you are not sure of their real purposes.

A bad example

1
2
3
int temp = sqrt(b ^ 2 - 4 * a * c);
solution[0] = (-b + temp) / (2 * a);
solution[1] = (-b - temp) / (2 * a);

A good example

1
2
3
int discriminant = sqrt(b ^ 2 - 4 * a * c);
solution[0] = (-b + discriminant) / (2 * a);
solution[1] = (-b - discriminant) / (2 * a);

Naming Boolean Variables

Below are the typical boolean names that are good to use.

  • done – Use done to keep if something is done.
  • error – You can use error to indicate if an error occured in the result of a process.
  • found – Especially, when searching for a value inside a list, initially set found to false. If needed value is found then set the found to true.
  • success or ok – You can indicate a result of a process if successful with success or ok. On the other hand, it would be better if you can replace the success with a more descriptive name like “processingComplete”.

In addition, you should give boolean names that indicate true or false. For example, done indicates if the process is completed or not. But, sourceFile doesn’t. Instead, you should use sourceFileAvailable.

Some programmers like to put “is” in front of the boolean variables. The benefit is, it prevents the usage like isStatus. But, it has bad readability when you use it like “if (isFound)”.

Using positive versions of the boolean names is always good. Because, when you need to use the negative result like “if not notCompleted” gives a bad readability.

Naming Enumerated Types

When naming enumerated types, the names should be simple. Also, the discrimination values should be definite. Thus, when you read the code where it is used, it must be like an English sentence. See the sample enumerations below.


1
2
3
4
5
6
7
8
9
10
11
12
public enum Color {
    Black, White, Blue
}
public enum Planet {
    Earth, Mars, Jupiter
}

if (color.equals(Black)) {//Here, it is as how you write it in plain English
//the rest code..

if (planet.equals(Mars)) {
//the rest code..

Naming Constants

When naming constants, name the abstract entity the constant represents. Do not give the name from the value. For example, “static final int FIVE = 5;” is a bad name. CYCLES_NEEDED is more proper. Because CYCLES_NEEDED can have different values like 6 or 7 but FIVE cannot have the value different from 5. As another example, “BAKERS_DOZEN” is a bad name. Instead, you can use DONUTS_MAX (remember the “Computed-Value Qualifiers in Variable Names” section).

Conclusion

In a nutshell, naming is one of the most important contexts while coding. Because it directly affects readability and the maintenance. Always consider that if another developer can understand what you have written. Most of the time, another developer will maintain the code you have written.

By the way, you can read my another post named “Keep Coupling Loose” from the same book.

References

Related Post