7.14 Add Comments
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);
}
|
