Skip to main content

July 08, 2014

Drupal Coding Standards

Thought by Matt Korostoff, Team Lead

We collaborate a lot at FFW. Not just internally, but with client development teams, our partners and, of course, the Drupal community.

Recently, a co-worker asked a question in our developer chat room about the value of coding standards. He clearly understood it, however, the client he was working with was committing code to a specific project’s git repo that was not in line with Drupal coding standards. The question he was essentially asking was, “How do I sell this client on the value of coding standards?"

Every developer has their own taste governing the use of white space, line breaks, underscores, and variable names.  Some prefer to_seperate_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 existing 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 and 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.

The strategic reason we abide Drupal coding standards:

Abiding by coding standards makes working in teams far easier.  Many teams will make small personalizations to the core set of Drupal coding standards, but it's important to have some set of standards, because otherwise everyone wastes time trying to (literally) decode each other's work.  When you spend a long time working with a given codebase you start to get a feel for how something should look.  When you scroll through a document quickly, in search of, say, a function definition, you're looking for familiar shapes and patterns to stop on and inspect closer.

It's the same reason that stop signs are all octagons—not because octagons are innately "stoppyer" than other shapes, but because the repetition allows drivers to quickly intuit the signs meaning at high speed and get on with the business of driving.  If some town made their stop signs crescent shaped, we'd probably all figure it out, but we would lose valuable time doing so. 

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

On average, code is read roughly 2 or 3 times more frequently than it's written.  Anything you can do to improve its 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:

return l('Log in', 'user/login', array('attributes' => array('target' => '_blank')));

Personally, I can't stand this, and I think it's unreadable.  My preference would be, by far, something with spaces more like:

return l('Log in', 'user/login', array('attributes' => array('target' => '_blank')));

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:

//settings for use in the l() function to make links open in new tab

$open_in_new_tab = array(

'attributes' => array(

  'target' => '_blank'

)

);



//Create a link to the user login page

return l('Log in', 'user/login', $open_in_new_tab);

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."

https://drupal.org/node/1354

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 http://i.imgur.com/BFInJqq.gif

The @ tags in docblocks are particularly useful, and can be used to generate automatic list in a wide variety of context, e.g. 

http://i.imgur.com/aLjgmeK.jpg

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:

http://i.imgur.com/iPoYarg.jpg

gives you this drush output:

http://i.imgur.com/DRlxRG9.gif

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.