This week’s post could be titled: ”things I wish I would have done right on day one” . The subject is how to properly document code with PHP comments and docblocks. This one took a while for me to really just accept as a part of the development process. To me now, the comments are now just as much a part of the application as the code is. I believe it is that important. With IDE’s today, there really is no reason not to have good documentation in your source code.
Why did I take so long to come around? There are two reasons: First, I was inherently a lazy hack at the time, just trying to patch a website together and move on. Second, I was under the delusion that I could remember what I was thinking at the time that I coded something. That did not work out so well. Once it’s written and deployed, you start losing that thought process and then the next project comes up, etc.
That’s what made me a convert. The amount of time I was spending trying to remember what I was thinking when I wrote something was adding up to more than I spent writing the application the first time around. Patches were a nightmare. One thing gets fixed and two more break behind it. Enough was enough. Just one problem…how was I supposed to document code anyway? Well, the first thing to do, obviously, was look it up on the Internet. So I did exactly the opposite….I made it up as I went….stupid, but better than nothing…I think.
Finally, I started it doing it like it should be done, and that is what we are going to cover today. First things first, what should be documented? To keep it simple, here are a list of things you should consider documenting:
- Classes (including properties & methods)
- Functions defined outside of a class
- Global Variables
- Includes & Requires
- The flow of execution of your application
The docblock is one of the main elements of source code documentation. A docblock starts with /** and has an asterisk at the beginning of each line. The docblock is closed with the */ characters. It is basically a slightly modified PHP comment block. An example of a method docblock from the CodeIgniter framework is shown below:
* Fetch an item from the COOKIE array
* @param string $index Index for item to be fetched from $_COOKIE
* @param bool $xss_clean Whether to apply XSS filtering
* @return mixed
public function cookie($index = '', $xss_clean = FALSE)
return $this->_fetch_from_array($_COOKIE, $index, $xss_clean);
The first line in the docblock is a general description of what the method (in this case) does. It should be as descriptive as possible, and you should remember that the person reading it probably didn’t write the code, so they need to be able to understand what you are saying. Within the docblock, you will also see different tags prepended with the @ symbol. These terms specify different aspects of whatever is being documented. In a class method or function, it is common practice to document each parameter (@param) and the return value (@return). There should be a note for the expected type of the value, and a description as well whenever needed. Whatever you are documenting, there will be a set of tags appropriate to the docblock. A file docblock for instance might include @author and @version. phpDocumentor has a very extensive manual showing all of the different tags that are available and what they mean.
Within the application itself, you should also consider documenting the execution flow, especially when it is not immediately obvious. There are 2 ways that this can be done, and both should be used together. The first is to code using meaningful names for variable, constants, etc. Yes, this means they will be a little longer, but done well, your code will document itself as you write it. Consider the following example:
$val = $_COOKIE['cookie'];
$session_id = $_COOKIE['session'];
Both lines of code do the same thing, but the 2nd example makes it very clear what is happening and what values are being dealt with. If you are still concerned that the code is not clear enough to someone opening the file for the first time, then you can improve it by using an inline comment, which is the second way to document the flow of execution. An example follows:
// Retrieve the session id from the stored cookie
$session_id = $_COOKIE['session'];
Once you have begun diligently documenting your code, then you can use automated programs to generate very nice looking documentation using programs like phpDocumentor and ApiGen. These programs will scan your code and create documentation of your application in a clean, readable HTML interface. An example of an ApiGen document is shown below:
I wanted to wrap these kinds of posts up with something like: “If you don’t do it this way, thean at least do…” This post is a little different. Documenting code in a standardized method is essential for the developer, the developers that follow the original dev, and the PHP community at large. Your documentation is as important as the code itself. If you can think of it in that mindset, generating solid source code documentation will not seem like a burden.