Documentation: The Unsung Hero

Documentation might not seem essential but once you sit down with thousands of lines of code that 25 people and a dog have had their hands (or paw) in, then you will see why without sufficient documentation you will find yourself in a World of Pain. I can share with you numerous examples and horrifying stories, but you will probably not believe me until you experience this Hell yourself. Well, you are reading this…so maybe you have already experienced this nightmare. I offer my condolence if this is the case and remember “what doesn’t kill us makes us stronger.” Anyway let’s move on, here are some things that I find extremely helpful to have and thus think important to do when writing your documentation.

1. First and foremost, comment as you go! This should be a given, but I’ve seen people in college wait until the program was working and met all the requirements to go back and write the documentation. This is after god knows how many changes, count variables added or debug cout statements. How do you expect to be able to write a coherent explanation of something you rewrote 100+ times while you were jacked up on RedBull?


2. Use Hungarian Notation – Hungarian Notation is a naming convention where the variable name indicates its data type or intended use. This is more for structured programming languages or hybrid languages like C++ (in a pure OO language, Hungarian Notation has no purpose). For example, if we are retrieving the age of the user and storing it in an integer we could name the variable iAge. If you couldn’t tell by the name “Age” that it would probably be an integer we have an i at the beginning to confirm it. This might not be the best example. Let’s take print, as it is named now we wouldn’t know what it is, but if we change it to fnPrint we know it’s a function or hwndPrint it is a handle to a window, probably the print window :-).


3. Document each Function and Class– Each function should be documented before the definition of the function. I have a certain format that I use, but it’s a personal choice. Here is an example of my method.
   /////////////////////////////////////////////////////////////////
   // BOOL fnStartApp (int iVar1, int iVar2)
   //
   // IN: iVar1 == *description*
   // iVar2 == *description*
   // OUT: nothing
   // RETURNS: success or failure
   //
   // This function spawns a new thread that runs an application… * detailed description
   // of what this function does, how it works, and any whys that might be needed
   //
   /////////////////////////////////////////////////////////////////
   I start with the declaration of the function. Then I describe what it takes in and what it sends out, I also describe what values the function can return. This is by no means the only way to do this; the most important thing is you answer the questions how and what. Some people suggest including why. As in why you chose to use vectors instead of arrays but these can be saved for an as needed basis. You don’t have to explain your preference for one data type over another.

These three simple things can make the lives easier for anyone who has to touch your code after you. I know that code is your baby and you don’t want anyone touching it and if they do you want them to be in agony, but think if it was you that had to follow behind someone. Don’t listen to those people “Real Programmers” do document. Remember, this isn’t the only way to document your code, and this isn’t a complete list but in this programmer’s opinion these are the most important.