Often underestimated and rarely understood, naming strategies in software development can make a huge difference in how well and easy code is understood. In my opinion, an intuitive naming strategy can be the most significant benefit to a software project. A good naming strategy will not only help programmers communicate better and more efficiently, but it can also help highlight weaknesses in the software architecture. When naming variables, functions and classes (in case of C++) a naming strategy that can address the following issues is paramount:
- Can the names be remembered without flipping back and fourth to their definition?
- Are the names reasonable in length?
- When reading a program, do the function and variable names tell the logic and sequence, without reading comments?
- Do the names imply a broad to specific meaning?
- Is there a naming strategy common for the entire project?
- Will two different programmers arrive at the same variable name, given the scope and responsibility?
Let’s analyze each of these topics independently now.
First, when writing new code if you find yourself flipping back and fourth to the variable declaration or you keep a header file always handy, this is a strong indication that the naming strategy you’re using can be improved. To help remembering variables, try the following:
- Do not use short-naming for common names. For example, try to avoid: img instead of image, num instead of number, lst instead of list, and so on. Instead, use the full name. It will not make the variable that much longer but it will help with memory and confusion.
- It is OK to use short naming (acronyms) when the variable refers to a name space or when referencing a common short name of well known acronyms. For example: OpenGL instead of Open Graphics Library, VTK instead of Visualization Toolkit and others. The expectation here is that an acronym can be used when it is well understood by programmers in the particular field of work.
Name Length and Program Readability
In the old days of programming, programming names could only be a certain length (such as 8 characters) and that forced programmers to come up with a wide range of naming strategies where the variable names looked more like an encrypted machine code rather than readable names. Those days are long gone and all modern programming languages will now allow longer variable names. Do not hesitate to use names that are reasonable in length, such as two to three words strung together. This usually helps with the readability of the code, to the point that comments can sometimes be skipped because the longer variable names can express the purpose and responsibility of their variable.
Broad to Specific
When naming variables, functions, classes, or anything in general, I prefer to use the logic of broad to specific. This is best given by an example. Assume that we have a variable that will keep track of the amount of tomatoes a farmer puts into his bucket during tomato harvesting season. The first try at this variable name might be: i. Yes, a generic loop variable that represents the number of tomatoes. A better name would be number and a better name still would be numberOfTomatoes. The broad name number clues the user that this is a counter and the second part of the variable is specific by telling us that the number keeps track of tomatoes. The name numberTomatoesBucket adds more specificity by telling the user that the variable keeps track of only the number of tomatoes in the bucket. Finally numberTomatoesBucketHarvest adds even more specificity and so on. How far one goes with the variable length is a bit of an art but the point is that one should think of the variable names as a beacon device that will hone the user into the variable’s responsibility.
Another nice benefit of this naming strategy is that if multiple names are grouped together, they are listed in alphabetical order keeping all the variables with similar responsibilities clustered. The names will also naturally guide the user to the sub-classing structure of the code.
Defined Naming Strategies
For a project to successfully use good naming strategies, the strategy needs to be published and be clearly communicated across the entire team. Naming strategies should be clearly marked like exit signs in a movie theater. Enforcing naming strategies can be done using a code review tool or other automated tools. The most important feature of a good naming strategy is not whether or not the strategy is the best strategy or better than another strategy, but whether or not the naming strategy brings consistency to the code.
The ultimate test of consistency is whether or not two different programmers will come up with the same variable name given the same variable responsibility.