New tools and an update on WSM Calendar

Well, I’m still working on the backend for the WSM calendar.  Every time I think I’m done, I find something else that needs doing.  Steve McConnell was right when he said development was an iterative process.  It’s coming along, though, and I’m learning more every day.

During this project, I’ve recently added two new tools (new to me, not new in existence) to my tool belt.  The first is a new editor.  I had been using Eclipse, which has some really nice features; the problem is the ever-mounting cost to be paid…bloat.  I guess every full-featured editor has it’s share of bloat, but the amount of it in Eclipse is bothering me more and more.  It’s pretty quirky, too—again, common among advanced editors, but it’s really beginning to bug me.  As an alternative, I’m trying NetBeans with it’s PHP plugin.  NetBeans is mainly focused on Java development, but it seems to be working great as a PHP editor.  It has similar features to Eclipse, and it’s quirks don’t seem to bother me much.  In fact, the only one that’s preventing me from doing something I’d like to do is a bug involving it’s Subversion integration.  It doesn’t play nice with gnome keyring (at least in Karmic) but this bug has been acknowledged and is supposed to be fixed in NetBeans 6.9.

NetBeans and Eclipse both have a nice integration feature that I just recently began to use, and this feature brings me to my next new tool: PHPDoc.  It’s a system that allows you to document PHP code in the source itself using special comments.  It’s really quick and easy to learn, and both of these editors are integrated with it such that they can parse/generate the comments for you.  For instance, if you type a function declaration, then go back and start a PHPDoc comment, it generates the skeleton of the function documentation for you.  Very nice!

The only problem I have with PHPDoc is the way it’s generated documentation looks.  The most common way to use it is to specify the HTML template, which turns your comments into static HTML pages.  The thing is, the default theme isn’t very visually appealing.  I couldn’t really find any third-party themes/stylesheets for it (I only searched briefly, though).  Actually, the only thing I’ve found is a template that churns out ExtJS widgets instead of normal HTML elements (at the moment I’m posting this, the website seems to be down).

I’ll eventually play with either the template or the stylesheet and get it to be more readable, but for now I’m just trying to make sure any new classes I code include PHPDoc comments.  Reading nicely formatted documentation is so much easier than opening a source file and skimming for a function just to check out it’s interface.  I don’t know how well this technique would stand up against various ideas about best practice, but I’ve been using the PHPDoc comments as a way to write out a sort of informal, passive version of a contract.  For instance, take the following function for example:

* Given a month (currently only accepts numerics), try
* to return a valid numeric month without leading zeros.
* If a valid month can't be returned, return boolean false.
* @param int $month The month to try to make valid
* @return int|bool
public static function makeNumericMonth($month)
        return false;
    //strtotime allows a month of zero, so we have to test for this manually
    if($month == 0)
        return false;
    if(strtotime("2010-$month-01") === false)
        return false;
    return ltrim($month, "0");

Here I’ve documented the assumptions, restrictions, and behaviors of the function with no “leakage” of the actual implementation.  I realize the danger is that something about the interface of the item being documented may change and the “contract” may not get updated, but that’s always a problem with maintaining documentation.  I figure I’m less likely to forget to update the docs if they’re right there in the code where I can see them.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: