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.