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.
The strategic reason we abide Drupal coding standardsOn 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-instanceHere'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 standardsHaving 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.