PhpRiot
News Archive
PhpRiot Newsletter
Your Email Address:

More information

Quality Assurance on PHP projects - PHPDocumentor

Note: This article was originally published at Planet PHP on 27 July 2011.
Planet PHP
It goes without saying people should document their code so that after a few weeks, months, years they still know what they did initially and why. Besides providing a mental note in the code, it also helps your IDE to figure out what your class is all about, which parameters should be used with the methods and what their return types are.

But theory is not always reality and unfortunately I've come across too many lines of code that were just lines of code, no comments or annotations provided. So, in best cases I could guess the types and parameters, but in many it was too obfuscated. I already talked about usage of a code sniffer like PHP_CodeSniffer in my previous post where you can validate the usage of comments in the code. But forcing developers (using a pre-commit checker) into writing documentation with their code is not really a good thing. Once people are forced in a corner, they tend to figure out ways to escape and your whole idea to deliver better code goes out the window.

As a consultant I face many situations where code is not documented or not documented enough, and the top 5 excuses I always get are:

  • writing documentation is not requested by the customer
  • no time, too many things need to be done between releases
  • too much work, and no one looks at the code anyway
  • why should I?
  • we charge extra for documentation, but the customer doesn't want to pay it

Like I said, these are mere excuses. I'm not here to judge these people, but I have to emphasize these excuses lack a real fundament to be acceptable in a professional environment. Maybe I'm taking to much pride in my "craft" as PHP developer, but don't you want to offer your customers the best you're company can provide?

Let's turn things around and imagine a new developer joins your team. Wouldn't it be great if you had documentation that could create complete documentation on the source code so it's easy to get into the flow of things? And when looking at the code in their favorite IDE whenever they access existing code, wouldn't it be great they could see instantly what parameters are used for a certain method or function with a brief explanation why it's useful? Maybe that's why I consider writing documentation part of writing code, invalidating all 5 excuses mentioned earlier.

Documentation 101

Writing documentation alongside your code is really not that much of work when you think of it. For all classes, you probably have a template that you can use that details your library of code components.

/**
A* My Awesome Library
A*
A* This library provides additional functionality and resources
A* for our standard framework [fill in your favorite framework]
A*
A* @category My
A* @license Copyright 2011 A My Company, Inc. - All rights reserved
A*/

When you actually write your class components, just explain in short what they do and why they've been created.

/**
A* My_Amazing_Component_Class
A*
A* This class provides amazing functionality that extends the framework
A* that's being used by this company.
A*
A* @package My_Amazing
A* @subpackage My_Amazing_Component
A* @version $Id:$
A*/
class My_Amazing_Component_Class
{
}

Once you get to the point where you write the method, you only need to provide some additional information about what it does, what the parameters are, the return types and if they throw exceptions or not

/**
A* We need to take two parameters to figure out which is the location
A* that we want to display on the map.
A*
A* @param float $latitude The latitude of the spot
A* @param float $longitude The longitude of the spot
A* @return string The link that displays the spot on a map
A* @throws OutOfBoundsException When values are invalid
A*/
public function findTheSpot($latitude, $longitude)
{
}

As you can see, not really difficult to get the documentation in place and when you do it immediately you don't even waste too much time writing it.

Automated API documentation

If you have the documentation in place, there are tools out there that allow to generate API documentation quickly and easily. There are less known but very promising tools like Doxygen, DocBlox, phpdocgen and many more. But the most known is still PHPDocume

Truncated by Planet PHP, read more at the original (another 2956 bytes)