Pages

2011/07/26

Quality Assurance on PHP projects - PHPDocumentor

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.

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

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

/**
 * My_Amazing_Component_Class
 *
 * This class provides amazing functionality that extends the framework
 * that's being used by this company.
 *
 * @package My_Amazing
 * @subpackage My_Amazing_Component
 * @version $Id:$
 */
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

/**
 * We need to take two parameters to figure out which is the location
 * that we want to display on the map.
 *
 * @param float $latitude The latitude of the spot
 * @param float $longitude The longitude of the spot
 * @return string The link that displays the spot on a map
 * @throws OutOfBoundsException When values are invalid
 */
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 PHPDocumentor. The tools that were mentioned here all have their pros and cons, but their usage is pretty simple and their outcome is exactly what you need to have good documentation of your source code.

PHPDocumentor is easy to use and requires just a couple of parameters to generate high quality API documentation.

user@server $: phpdoc \
  -o HTML:frames:earthli \
  -ric docs/README.txt \
  -ti "PHPDocumentor Example" \
  -dc MyCompany \
  -dn My_Amazing \
  -d application/models,application/forms,library/My \
  -i *.phtml \
  -t docs/api

Options used here:

  • -o HTML:frames:earthli defines the template to use, in this example we use the framed earthly HTML template
  • -ric docs/README.txt defines the README, INSTALL and CHANGELOG files
  • -ti "PHPDocumentor Example" provides the title
  • -dc MyCompany sets the default category if no category is being provided
  • -dn My_Amazing sets the default package if no package is being provided
  • -d application/models,application/forms,library/My defines the directories that contain the php code you want to document
  • -i *.phtml defines files that should be ignored when rendering
  • -t docs/api defines the location where the API should be generated
Running it on command line will look more or less like this


The result of it is that you get very nice documentation that can be handed out to all developers on your team, third party service providers building on top of your applications or new people on your team.

As you can see, isn't it great to have documentation with your code that requires not much of additional work? Don't forget, it's not just great to create smashing API documents, but it also helps your IDE as it will be able to give your more detail what kind of parameters and methods your classes provide and need.

14 comments:

  1. I would not recommend PhpDocumentor anymore, because its quite outdated and it seems, that there is no development anymore.

    ReplyDelete
  2. Great post! I'm subscribing to it. I'm just a newbie, but I've been learning php basics for few weeks now. Your post makes me realize how important documentation is on your scripts. Thanks for the post!

    ReplyDelete
  3. > @param float $latitude The latitude of the spot
    This is a bad description, something that I could figure out from the method name ("findTheSpot") and the parameter name itself.

    Better would be:

    > @param float $latitude Latitude of the spot in degrees , ranging from +90.0 (north) to -90.0 (south)

    ReplyDelete
  4. Also see http://blog.liip.ch/archive/2011/07/26/phpdoc-compilers-and-inheritdoc.html for a list of PHP documentation generators.

    ReplyDelete
  5. Hi,

    a good alternative to PHPDocumentor - since it seems to have been abandonned for more than 3 years now - is Doxygen (http://www.doxygen.org)
    It does the same thing, is quite configurable with a simple conf file, and is still maintained.

    Oh, and many thanks for your quality assurance series, it is really interesting and useful ! :)

    ReplyDelete
  6. Hey Mike, thanks for mentioning DocBlox!

    It is worth mentioning that phpDocumentor does not support 5.3+ features such as namespaces.
    DocBlox and Doxygen both support these new features.

    (I am not going to comment on which one does a better job; I am biased ;))

    ReplyDelete
  7. "no time, too many things need to be done between releases"

    That is the only reason i can understand. It's not a good reason, but i can understand how deadlines can cause these things.

    All other reasons were quite shocking, to be honest.
    If a developer doesn't know why he should be documenting, something is very wrong.
    If a company charges extra for documentation (i'm assuming we're talking about code documentation here) there's something even more wrong.

    ReplyDelete
  8. Very nice post Michelangelo! Documentation is definitely important for coding productivity. The documentation should contain good information to assist coders to get their work done.

    Last time I used Phpdocumentor for a large PHP project, it got overloaded, ran for a very long time, and used all the memory on my workstation until phpdoc finally crashed. I think we need another tool that is more efficient.

    I tried getting Doxygen to process PHP code, but couldn't figure out the right options and I ran out of time. Have you gotten Doxygen or the other tools you mention to work as a substitute for phpdoc?

    If you have interest in doing that, and comparing them in terms of compatibility, processing time, memory usage, and quality of output, that would be a truly great blog post.

    ReplyDelete
  9. Anonymous29/7/11 00:25

    Great post! I think it's worth pointing out that PHPDocumentor is no longer maintained and does not support PHP 5.3+ features. I've used Docblox and it works great!

    ReplyDelete
  10. Doc comments are overrated. On the contrary I believe better documentation could be generated from the test names. Documentation is for algorithms and subtleties you might have forgotten next time you look at it.

    See also Robert Martins post here:
    http://www.coderanch.com/t/131142/Agile/Javadoc

    ReplyDelete
  11. Example: Why the hell do you need something like "@param float $latitude The latitude of the spot"? Shouldn't that be obvious from the code? If you name your tests with intention revealing names, dito for parameters, why do you need this? You could generate it automatically from the code and everybody would understand. Now it is only duplication, which should be avoided. @Return can be interesting... because PHP doesn't let you specify it (yet).

    Can you show me an example where phpdoc gives meaningful info that I can't get from reading the class/method signature (I know PHP doesn't provide primitive type hinting yet and return types).

    ReplyDelete
  12. @KingCrunch: yes, I'm fully aware of it, but on most projects I've been involved with it suits my needs more than enough. But, if you have an article about another documentation generator, let me know and I'll add it here.

    @Nestor Rojas: Thanks for your kudos. Much appreciated and very welcome. Do take note of the comments here as PHPDocumentor is quite outdated and other tools are performing better and with less resources. Maybe someone will post an article about it.

    @Christian Weiske: You're absolutely right! My bad!

    @Lewis: Do you have a blog post on Doxygen? Would like to see how easy it is to set up and integrate with other tools like phing or Ant. Thanks for your kudos, much appreciated.

    @Mike van Riel: Hehe, it's because you showed me DocBlox at the DPC uncon and since it's supported by phing I could not include it in my list. Yes, you're absolutely right: PHPDocumentor is not PHP 5.3 ready, but unfortunately I'm not (yet) working on projects with PHP 5.3 code. Do you have an article how to set up DocBlox and how to integrate it with tools like phing or Ant? Would be a great addition to these series.

    @Oneway: I know it's quite unbelievable but for the past decade these were the answers I got when I pointed out the missing documentation in the code. I know it's not a perfect world out there, but I started to do something about it by posting articles to show it's not really that difficult to start improving quality assurance. A little step towards awareness and better code.

    @Bill Karwin: Hey Bill, thank you for your comment here. I have no experience with the other tools and from time to time I do face the limitations of PHPDocumentor, so I know what you mean. Hopefully Lewis and Mike van Riel will post an article about Doxygen and DocBlox as they seem to know these tools. With their articles I might be able to set up a benchmark system to compare all tools using the same codebase and environment, but as I stated… I haven't got around to figure out the other tools. Maybe the future will give me some spare time.

    @Anonymous: If you have great experiences with Docblox, would you write an article on it and link it back to me? Would be very much appreciated.

    @Koen: Documentation provided by your tests are very helpful, but I have to argue your statement that it's overrated. API documentation is still the only documentation you can provide to third-party service providers, and don't forget that your IDE uses that same in-code documentation to hint about params, methods and classes. But true, your test methods should be clear and state what's being tested (this is going to be mentioned in another article soon)

    ReplyDelete
  13. Eclipse does fine without in-code documentation (most of the time). The API documentation could be generated without PHPDoc too (eg by using reflection, at least from the moment PHP allows return types and primitives for methods). I'm open for a challenge: provide me with a zend framework class (not 1000 lines long) and I'll try to provide an alternative API generated documentationthat doesn't contain duplication.

    ReplyDelete
  14. There is a new version of phpDocumentor. It supports php 5.3. and I like it ;-)

    ReplyDelete