EchoDitto Blog

Getting Ahead of Drupal's Coding Standards w/ Drupal Code Sniffer, Vim and a little Regex

If you've submitted a project for consideration in a Drupal.org project
application or issue queue, you may have received a review that looks something
like this, a seemigly-endless stream of errors relating to
whitespace in comments, function argument documentation format, and horribly
malformed "else" statements. We can thank Drupal Code Sniffer and
it's web-service offspring, the Automated project review tool at
ventral.org, for much of this turn toward strict compliance reviewing. While
we all know that it's "the right way to go", it can often be quite discouraging
to hvae to churn through a list of what feels like miniscule issues in order to
share code with the community, especially when many of those issues are caused
by inconsistencies between standard code editor templates, documentation
auto-generators, and what Drupal.org requires.

The good news, though, is that we can get one step ahead of the review process,
and integrate these new tools into our development environment to ensure that
the code we write for Drupal is alway 100% compiant, from the start.

Drupal Code Sniffer is built on the widely-supported PHP_CodeSniffer
PEAR package and intended to be easily run w/o setting up an entire Drupal
instance (something that distinguishes it from Coder, for example).
This means that it can be integrated with any editor that has PHPCS integration.
The project page for DrupalCS has instructions for integrating with
Eclipse, and integration with Textmate, Emacs and
even Coda should be possible with their existing PHPCS extensions
(see links).

My editor of choice is Vim, however, and recent updates to the awesome
Sytastic vim plugin make working with DrupalCS darn near
enjoyable...almost. I'll share the set up for in-editor standards checking here,
and then a few of the naughty regular expressions I put together to help take
care of some of the most, well, annoying, ones in bulk.

It's really pretty easy to set up Syntastic to automatically check your code
against Drupal coding standards. Here's the quick step-by-step:

  1. Install Syntastic. I personally use the pathogen + git
    submodules
    approach for organizing plugins, and recommend
    it highly. You can use whatever approach works best for you (or is most
    coolest, as of the time you're reading this), but be sure to use
    Syntastic 2.1 or later. If you're
    using submodules to mannage your git plugins, this can be done by changing
    into your .vim/bundle/syntastic directory and running the command
    git
      checkout 2.1

    (or whatever release is newest).

  2. Install Drupal Code Sniffer. The easiest way is to follow the
    installation instructions on the module's project page:
    1. Make sure PEAR is installed.
    2. Run pear install PHP_CodeSniffer.
    3. Download DrupalCS (most recent version as of this writing can be
      downloaded here), and put it somewhere that makes
      sense (on *nix and OS X systems this is probably /usr/local/share,
      ~/bin or similar).
    4. Symlink the DrupalCodingStandard directory in your DrupalCS install
      to the Standards dir in CodeSniffer with a command like
      sudo ln -sv
       /path/to/drupalcs/DrupalCodingStandard $(pear config-get
       php_dir)/PHP/CodeSniffer/Standards
  3. Then we need to tell Syntastic to use the Drupal coding standards when
    running PHP CodeSniffer. To do this, add a few lines to your .vimrc
    file, telling Syntastic to use the DrupalCodingStandard standard and
    include the Drupal PHP extensions among those it subjects to its check:
    let g:syntastic_phpcs_conf=" --standard=DrupalCodingStandard --extensions=php,module,inc,install,test,profile,theme"

And that's it! I also like to add some lines like these to my .vimrc to
get the most out of Syntastic via the statusline and such (note that these also
require the amazing Fugitive plugin to work as-is).

With this configuration, Syntastic will scan your file for potential coding
standards violations on evey save, and display indicators on any line that
triggers an error. My editing environment looks something like this, then, with
a file that has some standards issues, after using the ":Errors" command to
bring up the error pane (note that these are due to cTool's Export UI's spec, in
this case):

This environment drastically reduces the number of coding standards issues that
you need to deal with in the review process...ideally down to zero.

Still, there
are going to be times when you need to get some code in shape that is just way
out of compliance. Toward this end, regular expressions can be a huge help as
well. I put together a set of fairly simple expressions to deal with some of the
most eggregious ones, which I use in the form of this simple sed
script
.

Full disclosure: this is a pretty clumsy and little tested solution. Known
issues include the fact that multiline inline comments will wind up with crazy
punctuation and capitalization if sentences span across lines. Fork the Gist and
help out!

Hopefully this will help others get to the place I'm currently at with
Drupal.org coding standards: finding them actually kind of perversely fun.
There's a good feeling knowing that your code is as rigorous as it can get and
will be a seamless part of the beautiful (if GIGANTIC) creation that is the
Drupal universe.

By the way, as of this writing the project application that spawned this post is
still awaiting approval. If you can, please take a moment to head over to
http://drupal.org/node/1369894 and help move the approval process along it would
be most apprecciated!

Tags: