Naming Variables

A well named variable is invaluable to good code. Poorly named variables can, in mild cases, be a simple nuisance. In severe cases they can hide defects or mislead programmers into creating defects. It can be downright embarrassing when your own badly named variables contribute to defect you put in the code.

The purpose of a variable is to describe the piece of information that the variable represents. Its name should be appropriate to the meaning of the data it holds.

The most common error in naming variables is being to stingy with characters. Short changing a variables name by using too few characters will generally cause you more grief that you will ever save in your reduced typing load. Its time to abandon the concept that we must severaly abreviate all of our variable name.
This tendancy to maximum our abreviation functions has persisted since the very early days of programming. I will dispense with examples from the past and get to the point.

It is time break with the past and indeed, with current custom, and begin to use descriptive names for variables. Some of the worst offenders are the books we buy to learn how to use various applications and to use as reference material. The Windows callback function in one starts like this:


01    LRESULT CALLBACK WndProc (HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
02{
03      static int cxChar, cxCaps, cyChar ;

and a bit further down has these lines of code:

09    TextOut (hdc, 0, cyChar * i,
10                     sysmetrics[i].szLabel,
11                     lstrlen (sysmetrics[i].szLabel)) ;

15    TextOut (hdc, 22 * cxCaps, cyChar * i,
16                     sysmetrics[i].szDesc,
17                     lstrlen (sysmetrics[i].szDesc)) ;

The significance of the variables cannot be easily determined. Yes, we can read the text and figure them out, but why not make the names obvious. This is a reference book that we will refer to in the future. The example should be code we should emulate, not struggle over. Here are some replacement lines.


01 LRESULT CALLBACK WndProc (HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
02 {
03    static int average_character_width; // was named cxChar
04    static int average_width_of_cap_character; // was named cxCaps
05    static int character_height; // was named cyChar

06    int column_one_left_edge = 0; // start with left edge of our window
07    int column_two_left_edge = 22 * average_width_of_cap_character;
08    int column_one_left_edge = 0; // start with left edge of our window
09    int column_three_left_edge = column_two_left_edge + ( 40 * average_character_width );

and the two TextOut lines become:

10    TextOut (hdc,
11                     column_one_left_edge,
12                     vertical_position,
13                     sysmetrics[i].szLabel,
14                     lstrlen (sysmetrics[i].szLabel)) ;
15
15    TextOut (hdc,
16                     column_two_left_edge,
17                     vertical_position,
18                     sysmetrics[i].szDesc,
19                     lstrlen (sysmetrics[i].szDesc)) ;

Variable average_character_width does not need a comment while cxChar tells us nothing more than it has something to do with characters, a fact that is already clear because of the hungarian prefix. The four characters C h a r do little good other than to differentiate it from the other two variables.
BTW: A well named variable has no need of a prefix to tell us what type of variable it is. First, if you name it well, its type is generally rather obvious, and when seen in context, there is seldom any doubt. Prefixes do little more than ugly up the code. Furthermore: This example uses a c or character prefix for some integers.
In lines 9 and 15 of the original, the author doesn’t even use variables, but hard coded constants with no comments. Lines 6, 7, and 8 of the replacement code declare some well named variables. The updated code flat out tells you what is going on. No comments required.
The variable i is a loop counter. In a short loop or tight context, a single letter variable can be just fine.

Spacing and Capitalization

The current standard for the capitalization and spacing of characters in variable name and functions is down right terrible.

IDoNotWriteTextLikeThisAndDoNotLikeToReadTextThatLooksLikeThis.

ThisStyleStinks!

I will be clear, this method of formatting names could not be much worse. What started it? My guess is that many of the people that wound up setting the standard did not want to use their right pinky finger to reach all the way up to that under bar just to the right of the 0 (zero) character. And at the same time, to press the shift key with their left pinky was all together too much. The heck with readability, that’s just too much work to write redable code. So rather than a minor reach with both hands, we have this nonsense of just capitalizing the first character of each phrase. Its difficult to read and downright ugly.

Using a space between phrases of a function or variable name is not allowed by any modern compiler. But using an underscore is trivially easy. I can hear the protests now and my reply is: Just because it has become a standard, does not mean it is either right or good. Violating the standard by using the underscore character does not at all make code more difficult to read because it doesn’t match the standard. It makes it much easier to read.

Constants

Everything said here applies to constants. The enlightened naming of constants will improve your code significantly. Most readers will recognize this line of code:

InvalidateRect( hwnd, NULL, TRUE );

Or if you feel a bit perverse you might write:

InvalidateRect( hwnd, 0, 1 );

But if you want to develop an attitude and reputation of writing readable code, you might try a few well named constants.

const BOOL ERASE_BACKGROUND = TRUE;
const RECT *ENTIRE_WINDOW = NULL;

InvalidateRect( hwnd, ENTIRE_WINDOW, ERASE_BACKGROUND );

This will probably solicit a number of boos and hisses from the many programmers that don’t write readable code. I might say there are quite a few of them that don’t want anyone to write readable code. My reply is simply: Nuts!

Conclusion

If you want to reduce your defect count by writing more readable code, if you want to write code that others can read with less effort, and if you want to be able to read your own code more quickly and accurately, then forget the tight abbreviations and jammed together phreses.

Use expressive variable names. Try it, you’ll like it.

April 2008