Professional C__ - Marc Gregoire [67]
Of course, we still advocate that you do some design of your program before jumping into the code.
Decomposition in This Book
You will see decomposition in many of the examples in this book. In many cases, we refer to methods for which we don’t show the implementations because they are not relevant to the example and would take up too much space.
NAMING
Your computer doesn’t care at all what you name your variables and functions. The compiler and linker also don’t care about how you name things as long as the names don’t result in conflicts with other variables or functions. Names exist only to help you and your fellow programmers work with the individual elements of your program. Given this purpose, it is surprising how often programmers use unspecific or inappropriate names in their programs.
Choosing a Good Name
The best name for a variable, method, function, or class accurately describes the purpose of the item. Names can also imply additional information, such as the type or specific usage. Of course, the real test is whether other programmers understand what you are trying to convey with a particular name.
There are no set-in-stone rules for naming other than the rules that work for your organization. However, there are some names that are rarely appropriate. The following table shows some names at the two extreme ends of the naming continuum.
GOOD NAMES BAD NAMES
srcName, dstName
Distinguishes two objects thing1, thing2
Too general
gSettings
Conveys global status globalUserSpecificSettingsAndPreferences
Too long
mNameCounter
Conveys data member status mNC
Too obscure, concise
performCalculations()
Simple, accurate doAction()
Too general, imprecise
mTypeString
Easy on the eyes _typeSTR256
A name only a computer could love
mWelshRarebit
Good use of inside joke mIHateLarry
Inappropriate inside joke
The previous table mentioned mNC. As a member variable this is too obscure and too concise. However, short names are allowed for local variables with a very limited scope. For example:
if (bError) {
CString s;
s.Format(...);
AfxMessageBox(s);
}
The details of CString, Format, and AfxMessageBox are not important for this discussion. What is important is that the variable name s is very short and not mnemonic, but it has a scope of only three lines. Its use is allowed because it is unlikely to be confused with any other variable in any other context.
Naming Conventions
Selecting a name doesn’t always require a lot of thought and creativity. In many cases, you’ll want to use standard techniques for naming. Following are some of the types of data for which you can make use of standard names.
Counters
Early in your programming career, you probably saw code that used the variable “i” as a counter. It is customary to use i and j as counters and inner-loop counters, respectively. Be careful with nested loops, however. It’s a common mistake to refer to the “ith” element when you really mean the “jth” element. Some programmers prefer using counters like outerLoopIndex and innerLoopIndex instead.
Prefixes
Many programmers begin their variable names with a letter that provides some information about the variable’s type or usage. On the other hand, there are as many programmers who frown upon using any kind of prefix because they could make evolving code less maintainable in the future. For example, if a member variable is changed from static to non-static, this would mean that you have to rename all the uses of that name. This is often time consuming and so most programmers don’t bother to rename the variables. As the code evolves, the declarations of the variables change but the names do not. This results in names giving the illusion of conveying semantics but in fact they convey the wrong semantics.
However, often you don’t have a choice and you need to