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

Why Comment?

Before we really begin, I’d like to take a moment and tell you why you should comment. As I have seen it, most people think commenting is a waste of time and resources. I’ve heard things like "you should be able to read code like English" or, "I don’t want people to know how my program works". Yeah - industrial spies are in your high school computer science class. Other people don’t even have reasons; they’re just too lazy to do it in the first place.

Commenting has many pluses. Not only does it let you track your work over a period of months and let you come back and remember what a certain function does; it can help you point out mistakes. For example, here’s a post off of GameDev.net message boards in the thread I started "Do You Comment?":

What’s wrong with the following pieces of code?

1) widgetCnt = widgetCnt + 1;

2) for (widgetCnt = 0; widgetCnt < NUMBER_OF_WIDGETS; ++widgetCnt)

3) if (widgetCnt < NUMBER_OF_WIDGETS)

Now here they are commented:

1) a typo

// create 100 more widgets

widgetCnt = widgetCnt + 1;

2) a cut and paste error

// loop through the widgets in reverse order

for (widgetCnt = 0; widgetCnt < NUMBER_OF_WIDGETS; ++widgetCnt)

3) used < when meant >=

// have we exceeded the maximum number of widgets yet?

if (widgetCnt < NUMBER_OF_WIDGETS)

If that example doesn’t give you enough reason to start commenting, then just don’t waste your time reading the rest of this article. If you don’t want to comment, that’s fine with me. Just don’t complain when you have your co-worker knocking on your door every five seconds to ask you yet another question: "What is this supposed to do?"

Commenting Code

The basic idea of commenting is to explain little snippets of code. To start, I’m sure you all know how to write a comment:

// this is a comment

Things to notice are a space after the two slashes "//" which start a comment, no capitalization is needed and no punctuation is needed. Now, if you had more than one sentence:

// sentence number one. Sentence number two. Sentence number three

It’s generally a good idea to follow normal punctuation up to the end. This is simply for clarity, as it makes it easier to read and understand if you can tell where a sentence stops and another begins. Notice I didn’t bother including a period at the end, since you really don’t need it.

The next important thing is a little gem known as white space. Because all spaces and comments are wiped out for compilation of the actual executable, white space is an extremely simple way to make your commented code easier to read. Here is a piece of code lacking white space:

// initialize the variable so it’s not full of garbage
int var1 = 0;
// set it to 10 for starters
var1 = 10;
// now add on an additional five so we can begins a loop
var1 += 5;

Very bundled up, and during late night coding sessions, I can guarantee you the comments and the code will blur together into an unreadable mess J. But add in the magical white space and:

// initialize the variable so it’s not full of garbage
int var1 = 0;

// set it to 10 for starters
var1 = 10;

// now add on an additional five so we can begin a loop
var1 += 5;

Viola! So much easier on the eyes as well as making individual statements easier to pick out, which is good.

I also like to tell people not to explain more than two unrelated lines of code with one comment. This is a good example.

// here we are going to call the first function, GetName() to get the name of the currently
// selected person, as defined by the variable name. Then we will call SetAge() in order
// give that person an age chosen by the user. Next comes SetGender, which also takes
// user input and sets the gender of the person. Finally we create the person with
// CreatePerson() and assign it to an instance of type PERSON
GetName(name);
SetAge(age);
SetGender(gender);
npc1 = CreatePerson(person.name, person.age, person.gender);

The problem with this is that by the time you’re done reading the comments, you get hit with the code all at once and say, "Wait - what was this for again?" And then you have to look back up and search the comments for the description you want. Yuck. But by commenting each function and throwing in some good ‘ol white space:

// get the name of the person we are using
GetName(name);

// set the age with a user selected age
SetAge(age);

// Set the gender with a user selected gender
SetGender(gender);

// create the person and assign it to the slot npc1, an instance of struct PERSON
npc1 = CreatePerson(person.name, person.age, person.gender);

Now that’s a smooth read. As soon as you finish the comment, you can check out the code, and then move on to the next line. If you ever have a question about the code, the comment is right there. Of course, the opposite would be a few related lines of code. It would be really stupid to do this:

// set x to zero
int x = 0;

// set y to zero
int y = 0;

// set z to zero
int z = 0;

Not only is it a huge waste of time, it’s repetitive! Repetitive comments are the worst things you could possibly do. If you find yourself repeating… yourself (errr….) then it’s best to just group the lines of code under one general comment like this:

// initialize the counters by setting them to zero
int x = 0;
int y = 0;
int z = 0;

This is allowable because all three variables are counters, and they’re all doing the same thing, so you only need to say it once.

The last little trick I like to use is the Tab key. It’s great for ordering your code and comments in a legible way. Take, for example, this section of code:

// define the states
#define GAME_END 1 // game is over
#define GAME_CONT 2 // person is still alive
#define GAME_PAUSE 3 // game is paused

// define the structure
typedef struct PERSON
{
  char name[50]; // the name of the person
  char gender; // male or female?
  int age; // how old they are
}

Aw man - my fingers were itching to press that Tab key while writing that. What a mess. The declarations flow right into the variables, which flow right into the values, which flow right into the comments. Wonderful if you want to read the code like a book instead of line by line but who has reason to do that? With the Tab key, referencing becomes much easier:

// define the states
#define GAME_END    1   // game is over
#define GAME_CONT   2   // person is still alive
#define GAME_PAUSE  3   // game is paused

// define the structure
typedef struct PERSON
{
  char  name[50];   // the name of the person
  char  gender;     // male or female?
  int   age;        // how old they are
}

Ta da! Now we can fully distinguish between the definitions, the variables, the values and the comments. Sure, color coding helps but if you ever get blurry vision (late night or anything else) the un-tabbed code will be a pain to read.

Next : Documenting Code