Upcoming Events
Unite 2010
11/10 - 11/12 @ Montrťal, Canada

GDC China
12/5 - 12/7 @ Shanghai, China

Asia Game Show 2010
12/24 - 12/27††

GDC 2011
2/28 - 3/4 @ San Francisco, CA

More events...
Quick Stats
88 people currently visiting GDNet.
2406 articles in the reference section.

Help us fight cancer!
Join SETI Team GDNet!
Link to us Events 4 Gamers
Intel sponsors gamedev.net search:

  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??