The importance of documenting your code

Does it feel like waste of time writing DocBlocks in the code you write? Are you one of those people who believe that code documents itself? These questions seems to be a constant battle among developers and those who favor documenting code.

I have done web development for twelve years now. Along these years, as incredible as it may sound, I have never started a work related project from scratch. Instead, I always managed to get right in the middle of the development where code base was pretty much in a state of working prototype.

One thing that I noticed each and every time I joined a project, was how complex it felt to get familiar with the code base that is not well documented. It's not like I didn't know how to read the code and learn from it, but how much easier it would have been to read a short description of a function, a little more detailed one and then read the usage for each of the variables used in the method. One glance, few seconds and I was on the right track about the function's usage and dependencies.

When we live in a world with globalization as a way of doing business, we must remember that a code our competitors write might end up in our hands at some point. I have seen it many times and I have experienced it first hand how it is trying to debug a spaghetti code with no documentation, either printed or inline.

But the main important fact is, that team members can and will eventually change in a project over time. Documenting code as much as possible is your way to show your professionalism and courtesy toward your fellow co-worker. It also allows new team members to get quickly familiar and comfortable with the project's code. Time is money, who has loose money to spend on pointless code familiarizing when it could be a snap.

Documenting your code is not hard, it's not a rocket science. I encourage you to read up a great tutorial of phpDocumentor by Gregory Beaver:

phpDocumentor Tutorial

I hope this blog post will bring you some thoughts on how you can improve the quality of code you write and how much it affects your co-workers.

Until next time, cheers!