matt's blog

DoxygenIt's been a few years, now, since I gave up using PHPDocumentor to document my PHP projects. I switched to Doxygen, an automated documentation tool that supports a wide variety of languages, including PHP. While PHPDocumentor enjoys broad support in the PHP community, Doxygen, too, is well entrenched. (Drupal uses it.)

I recently began a new project from scratch, and it gave me an opportunity to once again turn a hard gaze upon Doxygen. After some careful reflection on my experiences developing this new medium-sized library and documenting it with Doxygen, here are what I see as Doxygen's strong and weak points when it comes to PHP API documentation.

Users of the Janus VIM suite may notice a change in the newest version of Janus. In previous versions, one could navigate around split panes (including to and from the file browser) by holding down COMMAND-SHIFT and then typing one of the arrow keys. This feature has been removed from the latest versions of Janus (I'm guessing because of some other conflict).

Here's how to add that back in.

1. Open your ~/.vimrc.after file.
2. Add the code shown below.
3. Save and restart VIM.

For a long time, it has seemed that when it comes to unit testing in PHP, there is only one game in town: PHPUnit. And in all fairness, it's popularity is justified. It is a good framework, and can generally handle standard use cases.

But recently I found Atoum. Not being one to start small, I began using it on a large (soon to be Open Source) project that I was writing from scratch.

Was it love or infatuation?

Atoum has some great out-of-the-box features:

• Support for PHP namespaces.
• Each test can be run directly.
• The CLI output is clean and intuitive.
• I love the method chaining support.

VIM with JanusLinux Mint claims to be the second most popular Linux distribution after Ubuntu. And it is largely based on Ubuntu/Debian. While there are many subtle differences, though, the main one is that Mint supports a broader range of desktop environments -- most notably, Gnome 3.

Janus is a package of tools that turn vanilla VIM into a powerful development environment. It is targeted at GUI versions (gvim and MacVim), and it comes with a large assortment of VIM plugins and scripts.

This short blog shows how to install Janus on a newly installed Linux Mint desktop. It assumes that you can run commands using sudo in a terminal.

In a previous post, I showed an example of cloning a module that included this command: git clone drupal://drupalcs. But I neglected to explain how this worked. I'm not sure where I picked this up (it was probably from Sam Boyer), but by adding a few lines to your ~/.gitconfig makes checking out Drupal projects and sandboxes easier:

[url "ssh://git@git.drupal.org/project/"]
    insteadOf = "drupal:"
[url "ssh://git@git.drupal.org/sandbox/"]
    insteadOf = "drupalsand:"

This allows you to use drupal://PROJECT_NAME to identify a project (module, theme) git repository, and drupalsand://USER/NID to checkout a sandbox. For example, I can clone one of my sandbox projects with this command, executed at the command line:

$ git clone drupalsand://mbutcher/1356522
Cloning into 1356522...
remote: Counting objects: 988, done.
remote: Compressing objects: 100% (466/466), done.
remote: Total 988 (delta 463), reused 878 (delta 404)
Receiving objects: 100% (988/988), 242.04 KiB | 354 KiB/s, done.
Resolving deltas: 100% (463/463), done.
warning: remote HEAD refers to nonexistent ref, unable to checkout.

Perhaps this sort of syntactic sugar isn't for everyone, but I find it to be a nice configuration short-cut.

SyntasticVim (VI Improved) is a powerful text editor that comes standard on most versions of Linux, OS X, BSD, and other UNIXes. With thousands of add-ons, console and GUI versions, and a fully scriptable environment, you can transform a humble text editor into a powerful development tool. In fact, there are several Drupal add-ons for vim.

In this article, I explain how to turn on syntax checking for PHP, adding code style validation along with error checking. We do this with three tools: The Syntastic Vim plugin, the PHP CodeSniffer PEAR package, and the Drupal Code Sniffer project from Drupal.org.

Not too long ago, I posted a blog entry about 5 reasons for using a virtual machine for Drupal development. At the suggestion of some commentors, I have started looking into using Vagrant to manage my VMs. There is an excellent Drupal Vagrant project that provides a great starting point. This article explains how to begin with that and modify it to suit your own needs.

iTerm as VisoriTerm2 is a replacement for the built-in Mac terminal app. It provides many terminal features you may be used to from other systems (ahem, Linux), as well as some unique features and tools.

When it comes to OS X integration, iTerm2 has some amazing capabilities. You can even configure it to emulate Visor. Here I explain how to configure iTerm2 to slide down from the top of the screen like a Quake-style Visor. You can get an idea of what this looks like from the image on the left (click on it for a full-sized version). The borderless terminal window slides down from the top when focused, and then slides back up when not used. Never again will you need to hunt through your open windows looking for the terminal.

By mapping the visor to a hotkey, it becomes easy to quickly access a shell wherever you are without even taking your hands off the keyboard. And then, just as easily, the terminal can be dismissed. This article explains how to set up a visor-like terminal and then map a hotkey.

You can set up iTerm2 to do this in only three steps.

The Drupal codebase upon which I work is now over a million lines of code (excluding whitespace and comments). It sounds impressive. But the reality of the matter is that the combination of lots of code and the Drupal way of doing things makes it not impressive, but a maintenance nightmare. Nobody on the current team knows what all of this code does or what it is for. Even limiting things to the custom modules, there still is no longer any member of the team who knows the code well. This, of course, isn't a criticism of the team or even of the platform, but a reflection on what happens when a codebase balloons over the years.

Reading Steve Yegge's post entitled Code's Worst Enemy hit home the concern I have with our code -- and with Drupal in general. (Update 10/29/2011: Steve Yegge's the guy who accidentally posted the Amazon/Services rant on Google+, and who unintentionally "quit his job" in the middle of his presentation at OSCON.)

I suggest reading the entire blog post on its own, but here are several salient details that need explicit mention, and that have a Drupal context:

• While some languages (Java) may exacerbate the problem, clearly ballooning code can happen in any language. And with a semi-opaque execution sequence (as we have in Drupal), the problem can be compounded by the fact that one cannot determine at a glance what code might be executed on a given execution. To know what code will be executed on a given request, you must know not just core and your own modules, but all of the installed modules.
• Design Patterns might deserve a measure of skepticism. Steve's point is that relying upon them can introduce needless complexity. He uses Dependency Injection as an example. Too often, design patterns are introduced for their own sake or because they look similar to what we want to accomplish. But then the need to (re-)architect in terms of the pattern sometimes overshadows the original goal of accomplishing a task.
• Copy-and-Paste (CAP) code is bad. Obviously. But because all of Drupal is a public API, I often see developers choosing to CAP code from function body to function body because they think that is more elegant than providing highly-contextual stand-alone functions that might be mistaken by other developers as "generally useful". (No, prefixing functions with underscores is NOT a good alternative. Lately, I've been encouraging developers to underscore all functions that aren't hooks or constructed callbacks because it's too easy to get hook/namespace collisions otherwise.)
• Unfortunately, Steve doesn't talk about YAGNI ("You Ain't Gonna Need It") as a good design principle, but the converse of YAGNI -- that tendency to attempt to solve all possible cases before there are any actual cases -- is a dangerous tendency in software developerment that must be countered in the name of simplicity and maintainability.

In hindsight, I'm surprised how long it took me to develop a strong appreciation of code formatting standards. It's not that I haven't followed them all along (most IDEs and editors do the lion's share of that for you). What surprises me is that I never really appreciated the value of following them. But managing a codebase of over a million lines makes it readily apparent that coding standards are a big boon -- and that lapses in those standards adversely impact the entire team.

The primary reason for coding standards is this: humans are worse at syntax parsing than machines are. Coding standards exist to make the code easier for humans to work with, and they do this by making the code more amenable to visual scanning.

There are four benefits to be gained from following coding standards: reduction of bugs, preventing new bugs, lowering the learning curve, and easing long term maintenance. I discuss them below.