Document Your Code

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.

Author: Jack Slingerland

I'm a software engineer working and living in Raleigh, NC. I work in Python, Django, Node.js, React+Flux, AngularJS, and PHP. I like to work out with Kettlebells, run, and spend my free time with my wife, cat, and dog.

10 thoughts on “Document Your Code”

    1. That’s a side effect of the code highlighting plugin I’m using. If you take a moment to download a source file or two, you’d notice that everything is properly indented. I don’t suppose you have a good code-highlighting plugin for wordpress?

  1. phpDoc blocks discourage function comments. It’s too much labor to type them up, so often the whole comment block is skipped. Or the anti-pattern: the IDE places a parameter stub, which then exists in lieu of a real description. (And anyway, phpDoc is not particularily useful in itself. All auto-generated API-only manuals are just awful.)

  2. Well written code is preferable to lots of comments. Rather than using a doc block to describe what a parameter is, give it a name that describes its purpose. The same applies to classes and methods.

    I do think doc blocks are useful for hinting types to your preferred IDE as PHP isn’t strongly typed, but I would rather cut the noise from the transmission where possible.

    This isn’t to say that doc blocks aren’t useful for public APIs – but even then, a nice set of unit tests is better than any written documentation as they describe exactly how the program should be used.

  3. Jack,

    You hit the nail on the head with this post. I remember several years ago, a huge turning point in my career was when I joined an enterprise team. One of the architects was tasked with helping me to get ramped up. He opened up a file he had written to show me the inner workings. The class had a block summary at the top, every method was documented, the variables were descriptively named. I remembered feeling distinctly embarrassed about the code I had written thus far. I mentioned this to my mentor (who coincidentally had also mentored the architect tasked with helping me) and I will always remember his response; “The key to success in the enterprise environment is to realize that you are a part of a team. Sure, you could crank out a bunch of undocumented code so cryptic that 6 months from now not even you understand what it does. But your teammates won’t love you for that. A better way is to write your code as simple and straightforward as possible. Use descriptive names, and document it not only for them, and for yourself. And when your teammates realize that working on your code makes their lives easier, THAT they will appreciate. You will simultaneously help yourself succeed, help your TEAM succeed, and thus help the COMPANY to succeed”.
    Probably one of the most important lessons in my career, and especially important when you are working in a specialized domain.

    Incidentally, I came here looking for best practices in PHP documentation, as I had previously been using JAVADOC syntax (mostly the same). Thanks for the info!

Comments are closed.