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

Documenting Code

When you document code, you take what you know of commenting and apply it on a broader scale. A simple, commented program will have a comment for every other line of code that needs explaining. That’s good for the developers - it doesn’t clutter it up and it takes less time to scroll through it and change things. But once you complete a project and go to store it away, rudimentary comments aren’t going to cut it. When you document, you explain things in greater detail so that anyone who comes to continue your work in some fashion months or years later can understand what you did.

We’ll start off with program headers. In the program header the person reading the file gets a quick overview on what they program is supposed to do. It is important to get the person in the right mindset so he or she can understand why you coded the way you did. The description should be short, yet detailed. After the description comes the name of the creator and then the date. After that you can add a little section for notes - any oddities you may have thrown in at the last minute or any incomplete areas of the program. Here’s an example of a program header I use:

///////////////////////////////////////////////////////////////////////////////////
//-----------------------------------WinSock.cpp---------------------------------//
//                                      v 1.2                                    //
//                                                                               //
// This program will initialize WinSock and then attempt to open a socket and    //
// send info  to the other computer. This is the client portion of the client-   //
// server model. After the data has been sent, the program will close the socket //
// and save the data to a file                                                   //
//                                                                               //
// Created by: Drew Sikora                                                       //
// Created on: 9.24.00                                                           //
//                                                                               //
//--------------------------------------Notes------------------------------------//
//                                                                               //
// The file save feature has not yet been implemented in this version. Also, we  //
// are trying to trace a bug in the send/receive section. Sometimes the packets  //
// are dropped for no apparent reason (not net congestion). Just re-run the      //
// program.                                                                      //
//                                                                               //
///////////////////////////////////////////////////////////////////////////////////

//////////////////////
// the program code //
//////////////////////

///////////////////////////////////////////////////////////////////////////////////
//------------------------------------WinSock.cpp--------------------------------//
//-----------------------------Copyright Drew Sikora, 2000-----------------------//
///////////////////////////////////////////////////////////////////////////////////

With the header (and the footer), we can just read the description and know what the program will do, from start to finish. Again, it’s not long, but it manages to tell you everything the program does. A little habit of mine is to keep the sentences from running against the slash marks like this:

…. it isn’t quite//

Instead, I like to leave a space, even if it means taking out the whole word:

…. it isn’t      //

Of course, this is the best-case scenario:

…. it isn’t quite //

But that doesn’t always happen. Anyway, that’s just me, you may not care. Also notice the header is completely boxed in, to separate it from the rest of the comments in the actual program. This is a good way to document. Another separator I use is the dash (-). They do a good job of breaking up comment groups inside the closed boxes. Finally, look at the footer, which marks the end of the program file.

Another use for a header is at the top of a function. This time, there is a function description, and a variable list. A notes section, as before, is optional depending on whether or not the function has any extreme qualities you can’t fully describe through your comments. Here’s an example of a function header.

///////////////////////////////////////////////////////////////////////////////////
//----------------------------------MakeWindow()---------------------------------//
//                                                                               //
// This function will take in parameters usually sent to a CreateWindow()        //
// function and use them to make the call to CreateWindow(). This is so the user //
// can make many windows without having to type out a new CreateWindow()         //
// function call with most of the same parameters                                //
//                                                                               //
//------------------------------------Variables----------------------------------//
//                                                                               //
// hwnd       - the window handle                                                //
// lpTitle    - the string to appear in the title bar                            //
// style      - window style flags                                               //
//                                                                               //
HWND MakeWindow(HWND hwnd, LPCTSTR lpTitle, DWORD style)///////////////////////////
{

  ///////////////////
  // function code //
  ///////////////////

} // end MakeWindow()

The function header serves mainly the same purpose as the program header, to let the reader know exactly what the function does, and why it does it. A CreateWindow() function has a lot of parameters that don’t change from window to window, so why retype them all? This function will do it for you. The description tells you this. Then you get the variables section so you know what each variable is supposed to do or represent. Notice I make the function declaration a part of the header-bounding box. This makes a nice transition from header to function, making the header seem more a part of the function itself. And then the function is ended with a comment to denote the close bracket. This is especially helpful so you don’t need to look back up at the end to see what function it is.

Of course, documenting doesn’t end here. The next step is to go back through the code and add in additional comments to explain certain areas in more detail. For example, a few months down the road, this may not cut it:

// define the structure to hold our packet info
typedef struct IP_HEADER
{
  char         packinfo[80];
  GAME_STATS   gamedata;
  WCHAR        packname;
  int          packsize;
  ADDR_HEADER  packaddr;
  UINT         packstyle;
} IP_HEADER;

That might be fine during development, but these things tend to fade from memory in light of other projects. Therefore, when you decide to look it over again, seeing this might be more beneficial:

// define the structure to hold our packet header, which is sent to the client and then sent
// to the other players, and contains game information (user pos, weapon, etc)
typedef struct IP_HEADER
{
  char         packinfo[80];  // any text message sent
  GAME_STATS   gamedata;  // structure to hold player info
  WCHAR        packname;  // used for client ID on the server
  int          packsize;  // in bytes
  ADDR_HEADER  packaddr;  // structure for packet addr, to and from
  UINT         packstyle;  // any flags - see PacketS.h
} IP_HEADER;

As you can see, not all the various fields worked as named. The field packinfo could have been named msginfo, but then you could figure it was some message setting. And you could have thought packname was used to ID the packet in the program, not on the server.

Well, this just about wraps up documentation, as well as the article. But I have one more section for you filled with odds and ends I couldn’t find a place for.

Next : Odds 'n Ends