This article is an introduction into the art of giving names to all constructs in your software.
What is Naming?
Naming is one of the most common activities in programming. You do it all the time. Every time you create a new variable, a class or a file you have to give it a name. Naming is also one of the most important activities, as the names you choose carry the meaning of your code. Good naming can make a difference between code that is easy to maintain and will enjoy a long life and a codebase that no one will want to work with.
The Basic Principle of Naming
The basic principle of naming is that you have to write for the reader of the code – and this is not the computer! Neither a compiler nor an interpreter care much for the name you choose. As long as they are consistent and comply with the programming language’s rules, they don’t care. Deep down, at the level of assembler instructions, the names will long be forgotten. The processor only knows about registers and memory addresses.
This means the only people who really care about the names in your code will be your fellow programmers and also your future self.
You have to choose names that reveal the intent of your code. Ideally, the reader of the code will be able to figure out the contents of a variable or the responsibility of a class just by looking at its name. He should not have to look at the declaration or all the uses.
If you choose names well, you will also have to use less comments. The name of a method and its parameters must make the intent clear, so you don’t have to state it again in a comment. The rule of thumb is to use a comment only to explain why a certain solution was chosen, not to describe what it does.
Consider this method declaration in C:
float div(float a, float b);
Looking at this declaration, most people would assume that this method performs a division of two numbers. But how can you be sure? For instance, in a stock market software, it could also return the dividend ratio of a stock.
The author of the method knows this, so he decides to add a comment:
/* Calculates dividend ratio a: Stock price in $ b: Dividend in $ Returns the dividend ratio. If a is 0, 0 is returned. */ float div(float a, float b);
Looking at the comment now, a reader can figure out what the method does. The drawback is that every time he encounters the method in use, he will have to check the comment to understand it.
Let’s try to express the comment in code instead:
/* stockPrize: stock price in $ dividend: dividend in $ If stock price is 0, 0 is returned */ float dividendRatio(float stockPrize, float dividend);
See how the names of the method and the parameters reveal their intent? If you encounter this method somewhere in the code, it should be clear what it does. You will only have to look up the comment if you want to know the unit of the parameters or what it returns in case the stock price is 0. The first point can also be eliminated. Instead of using a float for the dollar amount, we can introduce a new type Dollar for the parameters.
/* If stock price is 0, 0 is returned */ float dividendRatio(Dollar stockPrize, Dollar dividend);
This way we can get rid of another comment. And now the compiler also makes sure that only Dollars are passed in as a parameters, not Euros or Yen. Only the last comment remains, as it cannot be expressed in code.
How to find a good name
This task consists of two different aspects. First, how do you choose names consistently in a project? This is codified in a naming convention. Second, how do you choose good names within these naming conventions?
Naming Conventions
A naming convention is a set of rules that are binding for all developers in a project, so that every developer knows how to choose and spell the names in his code. These common rules make sure that a developer looking at someone else’s code can understand it more easily.
Spelling
A naming convention is to govern the spelling of the constructs in the software. One rule could specify that every class or type name must start with a capital letter, and every method or variable name must start with a lower case letter. It might also say that constant names be written completely in capital letters, so that they can be spotted easily. Following these guidelines, you will easily recognize what is a type, a variable or a constant.
Names with Multiple Words
Another important rule for a naming convention is the spelling of names that consist of multiple words. Rules that are often used are:
- Camel Case: The first word starts with a small or capital letter, all following words with a capital letter: variableNameWithMultipleWords, TypeNameWithMultipleWords
- Snake Case: All words are separated with underscores: variable_name_with_multiple_words
Prefixes
Some naming conventions also state that all member variables of a class should start with a prefix, like mUserName or _spellChecker.The goal is to distinguish in the code when a member variable is used and when a local variable is used. And in some projects the names of parameters have to start with a p.
In my opinion, these rules are not obligatory. If you keep your methods sufficiently short, you will not need them at all. Under these conditions, you can see which variable was declared inside the method, which one is a parameter, and which one was not declared inside the method and therefore must be a member variable. In some programming languages like Python, you don’t need this rule at all because it forces you to prefix every access to a member variable with self.
Naming files
The naming convention should also include a rule how to name files consistently and how the folder structure should look like. The easiest rule is to put each class into a separate file. This file should then receive the name of the class. Thus you have a one-to-one relationship between class names and file names, without thinking hard about the latter.
Abbreviations
It is also important to handle abbreviations correctly. You should allow them for universally known concepts, like IP for Internet Procotol, or for abbreviations commonly used in your problem domain. Explain commonly used abbreviations in a central place, like a readme file or a wiki. Developers should only use these abbreviations in their names. Don’t allow developers to use their own abbreviations just to make the names shorter, because no one else will understand them.
For abbreviations, also the spelling should be specified. For instance, it could be specified that abbreviations with two letters can be written in all capital letters. For the ones with more letters, only the first letter should be a capital letter. This way you prevent unwieldy names like TCPToUDPBridge. It is hard to see where the abbreviation ends and the next word starts. It becomes much easier to read if you spell it TcpToUdpBridge.
When do you need a Naming Convention?
At this point you might be wondering whether you need this for a personal project or for bigger projects only?
In my opinion, you should have a naming convention for every project, including one man projects. It will help you keep the names consistent. And it will save you work if your project gets bigger and you will work with collaborators.
Fortunately, you don’t have to come up with a convention yourself. There are plenty of suggestions in the Internet. And many communities, like for Python and Ruby, have universally accepted conventions.
And if you roll your own, don’t worry too much to get it absolutely right. It is more important to have a guideline that everybody follows than to have the perfect convention that nobody uses. Just make sure to document it well, e.g. in a readme file.
Choosing good names
After a while, the basic rules for naming according to the naming conventions will become automatic. But you still need to decide which names to give.
A general rule is: Make class names nouns and methods names verbs. Think about it like this: When you write code, you create your own language to solve a problem. And in this language the classes are the nouns and the methods become the verbs. With them, you can create sentences. These are your program statements. And the better you choose the names, the more understandable your sentences will be.
Classes
The name of your class should be a noun that clearly depicts the responsibility of the class. For instance, a Parser class would be too general. What does it parse? So maybe MathematicalExpressionParser would be a better name. It shows the responsibility of this class – to parse a mathematical expression. And this should be the only responsibility of this class. It must not do something else. A name like MathematicalExpressionParserAndCalculates is not only too long, but it is also a hint that it has too many responsibilites. It is better to split it up into classes with only one responsibility each.
Also, avoid using too unspecific words like Manager or Handler in your type names. These words don’t give any clue about the responsibility. What would a class UserManager do? Does it hold all instances of users? Does it grant access for users? Does it do all of these things? You need to find a more specific name. And when a more specific name includes multiple responsibilites, you might consider to split the class up like above.
If you cannot come up with a good name at all, this is a sign that you are not clear what the class’s responsibility are in the first place. Resist the temptation to leave the name as it is! You should see this as an opportunity to improve your code. Lack of clarity in programming is one of the biggest sources of errors. So thinking about the name upfront forces you to be clear about the purpose of the code. This in turn helps you to write code with fewer mistakes.
Often you will find better names later on. In this case, go ahead and change them. With refactoring support in modern IDEs, you can do it in a few seconds. And it might save you and your colleagues hours of work later on.
Methods
Method names should always be verbs. They need to state clearly what they do. So don’t just call them execute(). For instance, a method that calculates something can possibly start with calculate.
Predicates – methods that take no parameters and return a bool – should begin with is, has or was. That makes their use much easier to understand. Consider this if statement:
if(request.success() && userList.empty())
{
...
}
What does empty() do? Does it return true if the list is empty, or does it empty the list and return success? It would be much easier to understand it like this:
if(request.wasSuccessful() && userList.isEmpty())
{
...
}
Length of Names
How long should a good name be? As long as necessary, and this depends on the context. In a local context, the names can be shorter and more general. In a global context, the names should be longer and more specific.
In a local context, you can easily check where a variable is used, so you won’t confuse the local variable count with some other count that was declared somewhere else in the class. The larger the scope becomes, the more specific the name needs to be. Often, but not necessarily, it makes the name longer.
Of course, the length of your names should still be managable. Often, all class names (except nested classes) are global, so they need to be unique globally. But you don’t have to choose their names just to make them globally unique. It is better to use namespaces, so the classes only have to be unique in this namespace.
But names also should not be too short. Resist the temptation of using one-letter names, as they don’t carry any meaning. The most common use of one letter names is for loop variables, which are often called i, j, k and so on. They make the code very concise, but also hard to understand. I have seen programmers scratch their heads more than once when they tried to figure out what the loop over k was doing in code they had just written. Imagine reading someone else’s code that was written this way.
Instead, you should always use names with a meaning, even if it is only for a very short loop. You never know in what way that loop will later be extended. And with meaning, I mean real meaning. Using index instead of i will not give you a clue, just more letters. A name like userIndex would be better.
Conclusion
Naming is one of the most important tasks in software development. With these rules in mind, you can write code that is much easier to understand. Don’t give up if you don’t come up with perfect names right from the start. You will get better at it.