Learn and Enforce Coding Standards with PHP CodeSniffer

Note: This post only considers the use of PHPCS with Drupal 7.

Open-source communities include contributors from a huge range of backgrounds and experience levels so a common baseline for those contributions is important. Since much of the communication in such communities happens in code, many OSS communities try to make community code adhere to a published “coding standard.”

A coding standard is a shared 'language' that facilitates communication between coders working in a specific project's ecosystem. Setting guidelines for code styles, makes it easier for anyone--including you yourself when you return to it after days, months, or years--to review, understand, and debug it. As the Symfony project’s coding standards page puts it, “…the main advantage of standards is that every piece of code looks and feels familiar.”

For this reason, your code should always pass Drupal's coding standards. This is equally true whether you're creating contrib modules to share with the community, writing custom code for your own projects, or building features for clients.

Many developers rely on their familiarity with Drupal's coding standards and produce high-quality code without further ado. But the larger the codebase is, and the larger the team gets, the easier it becomes for small inconsistencies to creep into the code. In this kind of situation, it can be beneficial to the project to enforce Drupal's coding standards, and useful to developers to provide immediate feedback when code fails to observe the standards.

This post is not so much a how-to--that territory is amply covered elsewhere--but rather a guide to how to put PHPCS to work at crucial stages in your development workflow.

Get PHP CodeSniffer

PHP CodeSniffer is the tool of choice for identifying departures from coding standards in PHP projects. The most flexible way of installing PHPCS is to use Composer--if you don't already have it installed, refer to Composer's installation instructions.

Once that's done, you'll need to install PHP_CodeSniffer.

PHP CodeNagging: PHPCS in your editor

This is where it gets interesting. It's been possible to run coding-standards checks using the coder module for a long time. But that required a specific, extra, manual step in the workflow--one that might easily be omitted under the pressure of deadlines etc.

With PHPCS globally installed, we can now use it to automate this step so that checks are run routinely on code as it is written, when it is written. We can, for example, run PHPCS on our code whenever it's saved, in popular editors such as Sublime Text 3, and (my personal favorite), Vim. Rob Allen's DevNotes offers an excellent how-to on setting up PHPCS in Vim or Sublime to get you started (and if you're a Sublime user, here's a sample config file).

Once this is done, the editor will display a mark in the gutter to flag a violation of coding standards, and a message in the status bar (like this one in Vim) advising the developer of the nature of the violation:

In my experience, this is tremendously helpful since it means that mistakes are flagged for me to correct immediately, and since it constantly refreshes my familiarity with the coding standards. This in turn leads to my making fewer mistakes of this type in the first place.

The power of embarrassment: PHPCS / TravisCI workflow

In spite of the benefits of having your editor gently remind you that you have made an error, your editor can't make you do to anything about it. But your colleagues can.

By combining GitHub and TravisCI to run PHPCS on every push and pull request, with the power of code-reviews, we can force ourselves and our colleagues to make every new line of code committed to the repository conform to the Drupal coding standards.

GitHub and Travis have a very tidy integration. A failing build looks something like this in real time:

When a build fails, it's possible to click the "Details" link and get a line-by-line breakdown of any problems encountered. The pull request keeps the red 'checks have failed' banner until the build has successfully run (though it doesn't prevent the code from being merged). This automatically incorporates two checks into my workflow:

1. I make sure the build passes before assigning the pull request to a teammate for review, and
2. If a broken build does slip by me, that colleague will immediately flag that as a problem for me to correct.

In other words, if you can convince your colleagues and peers to hold you to a reasonable minimum standard (that is if they won't sign off on your code if it fails PHPCS tests), your workflow will ensure that all of your future code will either conform to the standard or deviate from it only for a very good reason.

This provides a reasonable assurance that you, your colleagues, and your clients will be able to understand your code when it needs refactoring or modification. It also helps to build the habit of following the project’s coding standards so that your contributions can be easily absorbed into the community codebase.