Chapter 4 Basics of Clean C++
It is the title of a movie, so obviously it is a string and not an integer! Do not include the type of a variable or constant in its name. In a following section on Hungarian notation, I will take up this topic again.
Avoid Cryptic Abbreviations
When choosing a name for your variables or constants, use full words instead of cryptic abbreviations. There should only be rare exceptions to this rule and only in the case that an abbreviation is very well known in a certain domain, for example, IBAN (short for International Bank Account Number) in the financial world.
The reason is obvious: cryptic abbreviations reduce the readability of your code significantly. Furthermore, when developers talk about their code, variable names should be easy to pronounce.
Remember the variable named nPar on Line 8 from our OpenOffice code snippet? Neither is its meaning clear, nor can it be pronounced in a good manner.
Listing 4-10 shows a few more examples of Dos and Don’ts.
Listing 4-10. Some Examples of Good and Bad Names
std::size_t idx; |
|
|
// Bad! |
|
std::size_t index; |
|
|
// Good; might be sufficient in some cases |
|
std::size_t customerIndex; |
// To be preferred, especially in situations where |
|||
|
|
|
// several objects are indexed |
|
Car rcar; |
// Bad! |
|
|
|
Car rentedCar; |
// Good |
|
|
|
Polygon ply1; |
|
// |
Bad! |
|
Polygon firstPolygon; |
// |
Good |
|
|
unsigned int nBottles; |
|
// |
Bad! |
|
unsigned int bottleAmount; |
// |
Better |
||
unsigned int bottlesPerHour; // |
Ah, the variable holds a work value, |
|||
|
|
|
// |
and not an absolute number. Excellent! |
const double GOE = 9.80665; |
|
// Bad! |
||
const double gravityOfEarth = 9.80665; // More expressive, but misleading. The constant is
74
Chapter 4 Basics of Clean C++
// not a gravitation, which would be a force in physics.
const double gravitationalAccelerationOnEarth = 9.80665; // Good. constexpr Acceleration gravitationalAccelerationOnEarth = 9.80665_ms2; // Wow!
Look at the last line, which I have commented with “Wow!” That looks pretty convenient, because it is a familiar notation for scientists. It looks almost like teaching physics at school. And yes, that’s really possible in C++, as you will learn in one of the sections about type-rich programming in Chapter 5.
Avoid Hungarian Notation and Prefixes
Do you know Charles Simonyi? He is a Hungarian-American computer software expert who worked as a Chief Architect at Microsoft in the 1980s. Maybe you remember his name in a different context. Charles Simonyi is a space tourist and has made two trips to space, one of them to the International Space Station (ISS).
He also developed a notation convention for naming variables in computer software, named the Hungarian notation, which has been widely used inside Microsoft and later also by other software manufacturers.
When using Hungarian notation, the type, and sometimes also the scope, of a variable are used as a naming prefix for that variable. Listing 4-11 shows a few examples.
Listing 4-11. Some Examples of Hungarian Notation with Explanations
bool fEnabled; |
// |
f = a boolean flag |
int nCounter; |
// |
n = number type (int, short, unsigned, ...) |
char* pszName; |
// |
psz = a pointer to a zero-terminated string |
std::string strName; // |
str = a C++ stdlib string |
|
int m_nCounter; |
// |
The prefix 'm_' marks that it is a member variable, |
|
// |
i.e. it has class scope. |
char* g_pszNotice; |
// |
That's a global(!) variable. Believe me, I've seen |
|
// |
such a thing. |
int dRange; |
// |
d = double-precision floating point. In this case |
|
|
it's |
|
// |
a stone-cold lie! |
75
Chapter 4 Basics of Clean C++
Note Do not use Hungarian notation, or any other prefix-based notation, by encoding the type of a variable in its name!
Hungarian notation was potentially helpful in a weakly typed language like C. It may have been useful at a time when developers used simple editors for programming, and not IDEs that have a feature like “IntelliSense.”
Modern and sophisticated development tools today support the developer very well and show the type and scope of a variable. There are no good reasons anymore to encode the type of a variable in its name. Far from it, such prefixes can impede the train of readability of the code.
At worst, it may even happen that during development the type of a variable is changed without adapting the prefix of its name. In other words, the prefixes tend to turn into lies, as you can see from the last variable in the previous example. That’s really bad!
Another problem is that in object-oriented languages that support polymorphism, the prefix cannot be specified easily, or a prefix can even be puzzling. Which Hungarian prefix is suitable for a polymorphic variable that can be an integer or a double? idX? diX? How do we determine a suitable and unmistakable prefix for an instantiated C++ template?
By the way, meanwhile even Microsoft’s so-called general naming conventions stress that one should not use Hungarian notation anymore.
If you want to mark the member variables of a class, I recommend you use an appended underscore instead of prefixes like the widely used m_..., as in this example:
#include <string>
class Person { //...
private: std::string name_;
};
Avoid Using the Same Name for Different Purposes
Once you’ve introduced a meaningful and expressive name for any kind of software entity (e.g., a class or component), a function, or a variable, you should ensure that its name is never used for any other purpose.
76