Lightweight Documentation
April 30th, 2008 | by admin | |For me, lightweight documentation is just another way of saying ‘good comments in code’. I do not want to have to create and maintain separate documentation for my systems, so I just make sure that every single page has relevant comments explaining what’s doing what.
The Advantages of Lightweight Documentation
At university, we were taught all about Heavy Documentation. ie. the formal documentation specifications, explaining every little detail of everything your system is doing. And guess what? Do you think those manuals we spent hours and hours on ever got used? Hell no. The next person on the project often ignores the documentation because it’s long-winded and boring. The end up calling you, because there were no simple lightweight explanations of things. Heavy documentation has it’s purposes, but I don’t believe it has a purpose in small-medium sized web development. Lightweight documentation through proper code commenting is the way forward.
Lightweight documentation is simple and to the point. It will explain what a chunk of code (or function/class) is doing, or what its purpose is. There’s nothing worse than coming into a project when the old developer has left and their code has zero comments, and YOU have to pick up where they’ve taken off. This has happened to me on numerous open source systems that I wished to modify for my own purposes. I just got lost in the sea of code because there were inadequate comments.
So What Things Are Important When Commenting?
You don’t have to get too formal about things, but since php functions don’t require types for parameters, a new programmer won’t necessarily know what types to pass for function parameters. And this is important information, as is information about what the function is actually doing.
For example
<?php
function get_result($var1, $var2){
//do something
}
?>
Take the above function, and imagine it has hundreds of lines of code. As a new programmer to this project, I would not know anything about this function. It has no comments, and I have no idea if the parameters are integers, or strings, or other.
This is what your code could look like with lightweight documentation:
<?php
/*
* @summary: this function does calculations based on var1, and then compares the results to numbers found in var2
* @param: var1 is an integer
* @param: var2 is an array of floating point numbers, that we get from the time management system
*/
function get_result($var1, $var2){
//do something
}
?>
Suddenly we can make sense of this function. Obviously if you are writing functions, you give them meaningful names, and meaningful parameter names. This function does not. But it serves the purpose of showing you the importance of lightweight commenting. Now I know what types var1 and var2 are, and we can start using this function, without having to spend 20 minutes scanning through the entire function figuring out what’s going on 
For You, The Programmer
Once you, the programmer, get into the habit of commenting, I think you’ll find it very beneficial for you, not just for future programmers who ‘might’ look at your code in the future. For example: If I’m thinking about a given function I’m going to write, I just start typing. All that information going through my head is useful stuff, and by writing it down, I can then review what I’ve written, find mistakes, fix them and improve my logic. So in the end I have great documentation and have taken a little extra time to make sure my function is both robust and performance friendly