Contents  Introduction  Documentation??  Why Comment?  Documenting Code  Odds 'n Ends  Printable version

Documentation??

Wait a minute, wait a minute - what in the world is this documentation stuff? We don’t document, we comment. What is this? To me, commenting and documenting are two different things, so allow me to explain.

Commentation

Commenting code is the simple part. A comment resides near the line of code that you wish to explain. For example:

// Increment x to a value of 10
x += 10;

Of course, the previous code would assume x had a value of zero, but that’s irrelevant for this example. Simply put, you comment to explain a line or two of code, nothing more. Something like this does not help at all:

// fill in the structure
struct.name  = SNAME;
struct.player  = P1;
struct.pFlag  = NODIE;
FillUp(&struct, 0, INDEX);

Whoa. While the first three lines do not need any extra comments thanks to descriptive variable names (covered later), what’s that last line do? Obviously, thanks to the comment, it has to do with filling the structure. But fill it with what? That line, although related to the last comment, still deserves a comment of its own:

// fill in the structure
struct.name    = SNAME;
struct.player  = P1;
struct.pFlag   = NODIE;

// the other fields are not needed, so fill them with zeros for now
FillUp(&struct, 0, INDEX);

That’s much better! Could we have guessed that? Probably. But why bother take the time to guess when you can be told outright what it does?

Commenting, as shown above, is a term best used when describing single or multiple lines of related code. Again, not too many lines of code should be described by one single comment.

Documentation

When you document code, you take on a wider view. I refer mainly to documenting in this article because it is a term that assimilates commenting into it. A commentation can be referred to as a documentation, but not vice-versa. Why? Because while the scope of a comment is only a few lines, documentation encompasses a whole function, or list of functions, or list of variables, or even a whole program. Here is an example of documentation and commenting put together:

///////////////////////////////////////////////////////////////////////////////////
//---------------------------------ChangeState()---------------------------------//
//                                                                               //
// this function will change the current state of the game. The current state    //
// defines whether or not the game still runs or if the game has ended. We use a //
// variable along with two #define values to determine the game state.           //
//                                                                               //
//-----------------------------------Variables-----------------------------------//
//                                                                               //
// current_state    - the current state of the game, on or off                   //
// change_state     - decides whether or not we have to end or continue the game //
//                                                                               //
STATE ChangeState(int current_state, int change_state)/////////////////////////////
{
  // use a switch statement to decide whether or not to end the game
  switch(change_state)
  {
  case DEAD:
    {
      // change the current state so that the game is over
      current_state = GAME_END;
    } break;
  case ALIVE:
    {
      // change the current state so that the game goes on
      current_state = GAME_CONT;
    } break;
  }

  // return the new game state
  return(current_state);

} // end ChangeState()

This is what a documented function should look like. It has a header explaining the purpose of the function as well as what each variable is used for. Inside the function body there are comments telling you what everything does.

Now, look at the function and pick from below what statements describe it correctly:

1. The function is documented
2. The function is commented
3. The function is documented and commented

First, scroll up and reread the definition I gave you on documentation. Then decide. If you chose A and C, then you’re correct. Give yourself a pat on the back. Could you get away with B? Maybe, but then you get the picture of a few measly lines of comments, not a whole header. Throughout the article I’ll change between commenting and documenting. Just remember that anything I say about commenting can be applied to documenting, but don’t try to switch that around. Things could get ugly.

Now that we cleared that up, let’s move on so I can start to show you how to comment and then expand upon that and document.

Next : Why Comment?