Commenting While You Code

Good comments are a pleasant surprise for anyone who's ever tried to revise someone else's program. Not too long ago, I landed a contract writing a guide for a new, company-internal programming language. Was there a spec? No. Were there sample programs? Not really. Comments in the source code? No—strike three. The lead developer and I spent a lot more time with each other than with our families for a number of weeks—good thing we got along. But why take that chance? Better to write your comments as you go. Here are some ways to structure comments within a procedure:

• In procedure headers, define what the procedure does and list the other procedures or global data the procedure uses.

• Before Case statements and other decision structures, briefly summarize the choices and the possible actions taken.

• Before loops, describe the processing that is performed and the exit conditions.

• Warn about assumptions by using the word ASSUMPTION: followed by a description of what is assumed. Use UNDONE to mark anything you need to get back to, and then use the Find command to return to these lines and resolve problems before releasing your code.