7.14 Add Comments

I l @ ve RuBoard

Don't be afraid to put any information you have, no matter how little, into the comments. Some of the comments I've used include:

 int state;  // Controls some sort of state machine int rmxy;   // Something to do with color correction? 

Finally, there is a catch-all comment:

 int idn;    // ??? 

which means, "I have no idea what this variable does." Even though its purpose is unknown, the variable is now marked as something that needs more work.

As you go through someone else's code, adding comments and improving style, the structure will become clearer to you. By inserting notes (comments), you make the code better and easier to understand for future programmers.

Suppose you are confronted with the following program written by someone from the "The Terser the Better" school of programming. Your assignment is to figure out what this program does. First you pencil in some comments, as shown in Figure 7-2.

Figure 7-2. A terse program

This mystery program requires some work. After going through it and applying the principles described in this section, you get the well-commented, easy-to-understand version shown in Example 7-7.

Example 7-7. guess/good.cpp

 /********************************************************  * guess -- a simple guessing game                      *  *                                                      *  * Usage:                                               *  *    guess                                             *  *                                                      *  *    A random number is chosen between 1 and 100.      *  *    The player is given a set of bounds and           *  *    must choose a number between them.                *  *    If the player chooses the correct number, he wins.*  *    Otherwise the bounds are adjusted to reflect      *  *    the players guess and the game continues          *  *                                                      *  * Restrictions:                                        *  *    The random number is generated by the statment    *  *    rand(  ) % 100.  Because rand(  ) returns a number   *  *    0 <= rand(  ) <= maxint  this slightly favors       *  *    the lower numbers.                                *  ********************************************************/ #include <iostream> #include <cstdlib>       int   number_to_guess;  // random number to be guessed int   low_limit;        // current lower limit of player's range int   high_limit;       // current upper limit of player's range int   guess_count;      // number of times player guessed int   player_number;    // number gotten from the player int main(  ) {     while (true) {         /*          * Not a pure random number, see restrictions           */         number_to_guess = rand(  ) % 100 + 1;         // Initialize variables for loop         low_limit = 0;         high_limit = 100;         guess_count = 0;         while (true) {             // tell user what the bounds are and get his guess             std::cout << "Bounds " << low_limit << " - " << high_limit << '\n';             std::cout << "Value[" << guess_count << "]? ";             ++guess_count;             std::cin >> player_number;             // did he guess right?              if (player_number == number_to_guess)                 break;             // adjust bounds for next guess              if (player_number < number_to_guess)                 low_limit = player_number;             else                 high_limit = player_number;         }         std::cout << "Bingo\n";     }     return (0); } 

I l @ ve RuBoard