Naming Strategies When Coding

When writing code, a good amount of time should be spent on coming up with precise names for variables, functions, and classes. A piece of code based on a good naming convention should require almost no additional documentation, or it has the potential to significantly reduce the need for documentation. (Documentation for the software design, describing intricate and higher level logic behind a particular implementation, is always recommended.) Here are a few naming strategies that can help improve the programming style and readability of the code:

1. For names of classes, use the library pre-name followed by a noun-based name describing the responsability of the class as much as possible. Nouns are better for class names than verbs are. Using nouns for class names allows one to mentally think of a class as an object, or many objects, that are connected within the design. For example, “dmaProcessor” as opposed to “dmaProcessing” or “dmaConverterType” as opposed to “dmaConvertingType”.
2. Using a present tense verb for function names, a verb that describes the responsibility of the particular function is extremely useful. For example: “FindMaximumPixelValue()” as opposed to “FinderOfMaximumPixelValue()”. Functions tend to imply active actions and thus they are more similar to verbs than nouns.
3. It is a good idea to always pre-define the constants in the code and to never use “magic” numbers when writing code. This really helps with the readability of the code, especially when revisiting old code. For example, assume we want to write a loop that counted from 1 to 12. A simple solution would be something of the form:
   
   for (int i=1; i<=12; ++i){
   out << "Count:\t" << i << end;
   }
   
   When reading this code, the first problem is that it’s not clear why “i” is used and second, why stop at “12?” A better, more self explanatory, way to write this loop would be:
   
   const int iNumberOfMonthsPerYear = 12;
   for (int iMonth=1; i<=iNumberOfMonthsPerYear ; ++iMonth){
   out << "Count:\t" << iMonth << end;
   }
   
   In the second notation the variable names tell us exactly what the purpose of this loop is. The loop basically counts the months in a year, or something to that effect. Notice, that there’s no need for more documentation to this code. The variable names automatically hint the user as to the meaning of the code. The code is self-explanatory.
4. Each class should have its own header and implementation files and be named the same as the class name (i.e dmaImage.h and dmaImage.cpp). This significantly improves the speed of searching for the class of interest, especially when the project is large and it contains hundreds of classes.
5. When naming a class the name should describe the class from its broad responsibility to its narrow responsibility. For example: “dmaDataBinary” versus “dmaBinaryData”. The reason for using a broad to narrow naming strategy is twofold. First, the names themselves automatically force a certain structure on the organization of the classes. In this case, from the name alone, it is immediately clear that “dmaDataBinary” might have a base class called “dmaData” and that there is also an expectation that there’s a class “dmaDataAscii”. Second, the file names are arranged nicely inside the directory structure, so you can easily find similar classes grouped together.
6. Using short-hand names for variables, functions, or any naming should be avoided. Instead, the full name of the variable should be spelled out. This, is something that’s extremely useful in speeding up coding and communication between developers. Instead of naming something: “iMyConfScrpt” use the full name instead: “iMyConfigurationScript”. While the variable name tends to be longer, it eliminates the extra lookup-table that a reader has to keep in their head and the next time the variable has to be written it will be spelled out correctly and it won’t be confused with “iMyCofigScrpt” or “iMyConfigScript” or any other short-hand permutation. This rule can be bent a little bit when using well known acronyms, such as GPU, OpenGL, or others.

– Darian Muresan