3.2 C Code

I l @ ve RuBoard

3.2 C++ Code

The actual code for your program consists of two parts : variables and executable instructions. Variables are used to hold the data used by your program. Executable instructions tell the computer what to do with the data. C++ classes are a combination of data and the instructions that work on the data. They provide a convenient way of packaging both instructions and data.

A variable is a place in the computer's memory for storing a value. C++ identifies that place by the variable name . Names can be any length and should be chosen so their meaning is clear. (Actually, a length limit does exist, but it is so large that you probably will never encounter it.) Every variable in C++ must be declared. (Variable declarations are discussed in Chapter 9.) The following declaration tells C++ that you are going to use three integer ( int ) variables named p , q , and r :

 int p,q,r; 

But what are these variables for? The reader has no idea. They could represent the number of angels on the head of a pin, or the location and acceleration of a plasma bolt in a game of Space Invaders. Avoid abbreviations. Exs. abb. are diff. to rd. and hd. to ustnd. (Excess abbreviations are difficult to read and hard to understand.)

Now consider another declaration:

 int account_number;   int balance_owed; 

Now we know that we are dealing with an accounting program, but we could still use some more information. For example, is the balance_owed in dollars or cents ? It would be much better if we added a comment after each declaration explaining what we are doing.

 int account_number;      // Index for account table int balance_owed;        // Total owed us (in pennies) 

By putting a comment after each declaration, we in effect create a mini-dictionary where we define the meaning of each variable name. Since the definition of each variable is in a known place, it's easy to look up the meaning of a name. (Programming tools, such as editors, cross-referencers, and grep , can also help you quickly find a variable's definition.)

Units are very important. I was once asked to modify a program that converted plot data files from one format to another. Many different units of length were used throughout the program and none of the variable declarations was commented. I tried very hard to figure out what was going on, but it was impossible to determine what units were being used in the program. Finally, I gave up and put the following comment in the program:

 /********************************************************   * Note: I have no idea what the input units are, nor   *   *      do I have any idea what the output units are,   *   *      but I have discovered that if I divide by 3     *   *      the plots look about the right size.            *   ********************************************************/ 

One problem many beginning programmers have is that they describe the code, not the variable. For example:

 int top_limit;     // Top limit is an integer [bad comment] 

It's obvious from the code that top_limit is an integer. I want to know what top_limit is. Tell me.

 int top_limit;    // Number of items we can load before losing data 

You should take every opportunity to make sure your program is clear and easy to understand. Do not be clever. Cleverness makes for unreadable and unmaintainable programs. Programs, by their nature, are extremely complex. Anything you can to do to cut down on this complexity will make your programs better. Consider the following code, written by a very clever programmer.

 while ('\n' != *p++ = *q++); 

It is almost impossible for the reader to tell at a glance what this mess does. Properly written this would be:

 while (true) {      *destination_ptr = *source_ptr;      ++destination_ptr;      ++source_ptr;      if (*(destination_ptr-1) == '\n')           break;  // exit the loop if done  } 

Although the second version is longer, it is much clearer and easier to understand. Even a novice programmer who does not know C++ well can tell that this program has something to do with moving data from a source to a destination.

The computer doesn't care which version is used. A good compiler will generate the same machine code for both versions. It is the programmer who benefits from the verbose code.

I l @ ve RuBoard