Thoughtful Variable Names

Variable names should involve thinking indeed.

Classes design and names help with identifying the purpose of a class. Method and function names help identifying the purpose of a method or a function. Variable names help identify the purpose of a variable.

Very often I find code that looks like this:

var dictionary = new Dictionary<string, string>();

or

Integer getTotal() {
	//...
	var result = calculatePrice();
	//...
	var total = result + taxes;
	//...
}

These sort of thing exists everywhere. Are they good? Are they bad? It all depends.

Variable names are meant for few purposes, and these purposes include at least this: to help the reader understand the code. Variable names do not help with understanding what the purpose of a method is: this is delegated to the name of the method and the class in which the method reside. Instead, variables help understanding how a method fulfill its purpose. In the previous example: result should help us understand how getTotal works in the context of getTotal. When you see the first line of getTotal, you understand that result resemble the calculated price. You did not figure that out because of the name of result (result can mean anything.) Instead, you understood that result represents the calculated price because of the calculatedPrice function. Its name indicates what its purpose is. result is not a helpful name.

If you read the second line var total = result + taxes;, you will see that result is surely not a helpful name. It is not clear how result is related to taxes or total. But the name total in the context of getTotal is very helpful: you understand immediately that this indicates the total or payment or transaction of some sort. taxes is also helpful because it validates our first thought about total. Result is not helpful, however. A better name is probably price.

As you can see, you can tell a lot about how getTotal works by good variable names. Not only that, you can sometimes know which variable is likely named poorly by looking at other variables that were named thoughtfully. This is really the purpose of a variable name.

In the first example, dictionary indicates its own type, and nothing else. It is very difficult to know what its purpose is. If I were to see this code without any context, I would assume that this is just a generic dictionary to hold anything. It would take me sometime to understand its purpose, if it has any.

Variable names are building blocks for understanding methods, and private fields (if there are any).

There are many books written on how to name a variable. How you can indicate its purpose without being overly pedantic about it. But these books usually do not consider the idioms in the language and the culture around the language, and sometimes does not consider the programming culture.

Short names can be ideal

In Go, there has been some idiomatic way of naming variables. For example, if the variable is short lived, then it should be named with a single character:

func someFunction() Response {
	r := getResponse()
	return r
}

It is acceptable to name that variable r, and the reason being that the variable is short lived and hence the purpose of that variable is clear at assignment. The letter r indicates that it is a Response variable. This practice is common outside Go as well.

Moreover, it is also common to use a double letter to indicate an “array” in Go:

func TestMyStruct() {
	tt := getTests()
}

tt is used instead of t to indicates that it is short lived and it is an array. Generally this is not a good practice but the community has adopted this convention that it became easy to understand.

Moreover, req can be used instead of request, and res instead of response. Sometimes, the full name of a variable brings less clarity than a short name. This is because there are likely classes with the same name.

String string = "something";
// vs
String str = "something";

In this example, str is better because everyone knows that str is a string, and string and String are too similar.

Use the conventional name in the language for certain entities

Another practice is to have a name that has a convention associated with it. For example, in C# it is common that people write:

using (var context = new MyDatabaseContext()) {
	return context.Table.DoSomething();
}

Even thought context by itself does not indicates that it is a database access layer, Entity Framework uses the word context to indicate that, and hence that is a convention used. In Go the word ctx is used to indicate the cancellation context. Each language has its own “reserved names” in a sense. It would be greatly confusing if one uses context in the database layer to mean something else.

Almost all languages use i for index in a for loop. You do not need to invent a new name of i is good enough.

Context is king

Context should guide you in variable naming. One might think that dict in this example:

var dict = new Dictionary<string, string>();

Is a bad name if dict is long lived. But that could be a good name if this dict is a general purpose dictionary. The context should decide if it is a good name or bad. Consider this example:

class User {
	private String userFirstName;
}

Although giving a precise description is good, here user is unnecessary because it is inside the User class. firstName should be enough.

Conclusion

General conventions are good. But I would suggest that you also learn the conventions of a particular language, particular community, and particular context. Unfortunately there are no hard rules, and there are grey areas. But in most cases the difference between a good and a bad name is clear, and the difference between a good name and a better name is also clear.