Tag: documentation

When you started learning to program, documenting your code was the last thing on your mind. You’re were here to learn, and learn is what you did. As your programs started to grow in complexity, your college professors preached to you “You must document your code! What if you have to come back to it in 6 months? Will you remember how everything works?”. So, you dutifully documented your code. But then something strange happened: you got a job. In the real world there are deadlines, and that extra minute you should have taken to document the code is gone. But the thing is, you MUST document your code. If not for you, do it for me. Because guess what, I’m the one that has to go in and fix it, and knowing what’s going on would make my life a lot easier.

A Story

When I started my current job, one of the other programmers was assigned to get me up to speed with our CMS. My first question was “Is there any documentation I can go over?”, to which he responded “Nah, just dive in and you’ll be fine.”. So I dove in and it only got worse from there. As I looked through the code, nothing was documented. Nothing! I spent the next 3 months sifting through code trying to figure out how it all works. I eventually did figure it all out, but it was 3 months where I was working at maybe 50%-60% of my maximum efficiency. Having any sort of documentation would have made this process much easier. Not only that, but because of the lack of documentation we constantly create duplicate functionality. After all, how are you supposed to know what functionality exists if there no documentation on it?

Now that I’ve been at my current job awhile, I’ve decided to change things. I’ve started taking 15 to 30 minutes a day to document our CMS using the PHPDoc format. It may or may not catch on with the rest of the programmers, but I know that every function and class that I write has full documentation, and it feels good when the documentation gets generated with PHPDoc. I believe the quote is “You need to be the change you believe in”.

How to Document Your Code

It’s easy. Really easy actually.

/**
* Function short description
*
* This is a long description of the function.  Discuss what this function does in
* any detail that is necessary.
*
* @global void $globalVariable
* @param int $aParameter This is the description of the parameter.
* @param mixed $bParameter This is the description of another parameter.
* @return bool This is a description of the return variable.
* @todo Does something need to be done?  Put it here.
*/
function my_function($aParameter, $bParameter) {
     global $globalVariable;
 
     //If you are doing something extra complicated, make a comment inside the
     //function.  Otherwise, you code should speak for itself.
     for($i=0; $i < 20; $i++) {
          echo $i;
     }
 
     return true;
}

That’s it. That’s all you need to get started documenting PHP code. There’s a lot more you could be doing, but it’s not all that important. So long as you document the parameters, the return type, and write a description about what the function does, you have the important bits.

So next time you think to yourself “I’ll document it later.”, just take the time to do it now. Because guess what? You aren’t going to go back. Something else is going to come up, and then the rest of us will suffer.