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

Introduction

You know, one day at work I was handed a program by my boss. He said, "Drew, see if you and Mike can figure out what this does and if it will be of any use to us." I said "Okay" and took it. The program was from two other employees in the small start-up company I work for who had quit a day or two ago. My boss had asked for what they had accomplished so far and the small stack of papers on my desk was the result. I took the main program file printout and started to look through it. After the first page, my heart rate began to quicken. A few more pages and I began to simmer. When I finally reached the last of the 15 pages I wanted to scream.

I walked into my boss’s office and asked if the two guys were gone for good. He nodded an affirmative. I showed him the paper and explained to him that this job could take a few weeks of work. He looked at me, puzzled. He hadn’t noticed. I handed him the paper and let him look through it. Nothing wrong, he said. I finally pointed it out myself:

"There aren’t any comments, Chief."

This is a good example of what happens to team players when the other team members don’t do their job correctly. In essence, I was handed a program filled with lines of code that had absolutely no meaning to me at all. This scenario only happened a week ago, but I’m still busy at my desk tracing routines, finding functions, tracking variables - and adding in my own comments. Luckily for me, my boss had been a programmer of old and lessened our other task loads so we could better focus on our current project. Can we do this? Yes. It will just take a lot more time than if the code were properly documented.

The purpose of this article is to show programmers, experienced and inexperienced alike, how code should be documented. It’s not just about you; it’s about the other members of your team. It’s about being nice to them and letting them be able to understand your code. It’s about keeping them from having to hunt you down so they can kidnap you, strap you to a chair, and have you divulge the secrets to your program. You wouldn’t want that, right? Didn’t think so.

NOTE: All commenting in this article is done using only C++-style comments (i.e. // and not /* ... */).

Next : Documentation??