Creative Juices

A blog by Matt Korostoff

Drupal Coding Standards

In this post we'll cover: why you should abide Drupal coding standards. I will give several concrete examples of real-world advantages to abiding Drupal coding standards.

Code style can be a deeply personal thing. Every developer has their own taste governing the use of white space, line breaks, underscores, and variable names. Some prefer to_separate_words_with_underscores othersPreferCamelCase. This is fine when we’re writing code for personal use, but when it comes time to merge work of divergent styles from multiple developers, you end up with an inconsistent mess.

Luckily, the Drupal community has this problem largely solved with Drupal coding standards. It can be difficult for a new Drupalist to understand why we have so many rules about code style, but anyone who's worked on a large project knows, you would be helpless without them. There are good strategic, as well as functional reasons to abide Drupal coding standards, and I'll go over both. As you’ll see, it’s well worth following the rules, even when you don’t agree with them.

Many countries employ the standard red octagon with the word “stop,” including countries that do not use the latin alphabet. Above, a stop sign in Greece. Credit http://www.ilankelman.org/stopsigns.html

The strategic reason we abide Drupal coding standards

On average, code is probably read 2 or 3 times more frequently than it's written. Anything you can do to improve it's structure pays future dividends every time it's read. There's a great video that explains this on buildamodule.com.

A simple for-instance

Here's a simple example of this principle in action. Drupal coding standards call for no spaces before or after the parameters in a function call. Usually that looks fine, but if you happen to be declaring an array inside your function call, it results in this mess: Personally, I can't stand this, and I think it's unreadable. My preference would be, by far, something with spaces more like: When I'm writing for my private use, I always leave spaces in my nested function calls. But now imagine this scenario: we discover a bug in one of our custom modules that causes a fatal error every time a nested array is declared inside the l() function. So we come up with a bit of regex to find all the instances of nested array declaration inside the l() function, which is actually pretty simple, so long as everyone is abiding standards: "l\(array\(.*array\(". But if everyone has followed whatever style they please, writing a regex that will match every possible variation would be close to impossible. So I follow this rule, even though I think the rule is wrong, because I know others will need to deal with the code I write. And, as an aside, in a real-world situation, I'd probably refactor the above as follows:

The functional reason we abide Drupal coding standards

Having a predictable, uniform code format allows us to build and use tools that depend on having a predictable structure. I think this point is fairly obvious to experienced developers, but allow me to give some drupal specific examples:
  • Standard comments can be parsed by the API module to create automatic documentation https://drupal.org/node/1354. :
    The API module parses documentation and code in PHP files, and it expects documentation to be in a format similar to other code/documentation parsing systems such as PHPDoc, JavaDoc, etc. It was originally based on Doxygen, but it has evolved into something that has its own set of tags and a lot of Drupal-specific functionality.
  • Standard function and class definitions can be parsed by IDEs and text editors to implement a feature like phpStorm's ctrl+click jump to function definition
  • The @ tags in docblocks are particularly useful, and can be used to generate automatic list in a wide variety of context, e.g.
  • Drush can parse docblocks to show useful output during deployment. Much of the advanced functionality in drush is made possible by the fact that drupal coding standards are abided so widely. For instance, this install file:

    gives you this drush output:
  • Autoformatters like Sublime's PHP tidy can take all the thinking out of code style—but if two people on the same project use different coding styles with autoformatters, they'll just constantly re-format each other's code, making a giant mess of the git history.

In Conclusion

Of course, your team might decide some aspect of Drupal coding standards are not right for you—that's not the end of the world. What's really important is that your team all find one standard and stick to it, because in the end:
Tags: 
Matt Korostoff is a web developer and cartoonist from New Brunswick, NJ. He works for Blink Reaction and you should too.