How to Implement Drupal Code Standards for Drupal 7, 8, 9, and 10

Once you know what code standards are and why you should use them, you need to learn how to implement Drupal coding standards in your projects. This tutorial will walk through some of the steps you can take to make this as easy as possible. We'll cover:

• Configuring your editor or IDE to warn you of coding standards violations
• Setting up the Coder module and phpcs to scan and review your code
• Performing team code reviews

By the end of this tutorial you should be able to configure your development environment and implement processes in your workflow that help to ensure your code meets Drupal's coding standards guidelines.

Goal

Configure your editor or IDE, and install Coder + phpcs to aid in reviewing code for coding standards compliance.

Prerequisites

• What Are Coding Standards?

Contents

• Configure your editor
• Review your code with PHP Code Sniffer
• Team code reviews

Read the coding standards and keep them handy

It’s a good idea to read over the Drupal coding standards so you have an idea of what’s expected. Even if you’re familiar with them, refresh your knowledge. They’re also a living document, so there’s a good chance something may have been changed or added since the last time you read them. Use this tutorial as a reason to read them again, if you've read them before. Make sure you have them bookmarked for reference, as well.

Set your editor up for success

The easiest way to keep your code clean and up to par is by having your editor do the work. There are a lot of editors out there, and even the ones that don’t have many bells and whistles can be set up to help you keep standards in mind when you’re coding. We'll take a look at the settings for two popular editors that work across all the major operating systems: Sublime Text and PhpStorm. If you’re using another editor, you can see if it’s listed in the Drupal.org Development tools overview.

Sublime Text

Sublime Text is a text editor that allows for a lot of customization.

The Drupal.org handbook has a page all about Configuring Sublime Text. Here you can find the basic configuration for adhering to Drupal coding standards, a script to set it up on OSX and Linux, and great plugins to help with development. Now you don’t need to worry about line length, spaces, tabs, line endings, and more. It’ll all be handled for you.

This post from our friends at Chromatic is a couple of years old, and geared towards front-end developers, but it has a lot of great setup tips and plugins for every developer.

PhpStorm

PhpStorm is a full integrated development environment (IDE) by JetBrains that provides text editing as well as additional tools for debugging your code.

The JetBrains website has extensive instructions for getting set up with Drupal configuration.

You can also view our tutorial Drupal Development Using PhpStorm which contains information about configuring PhpStorm for use with Drupal as well as demonstrations of the features this integration enables.

Review your own code

The easiest way to make sure you’re conforming to coding standards is to use a program like PHP CodeSniffer. You can install Coder, which is a Drupal module that allows you to check your code from the command line using custom rules and PHP CodeSniffer. Here’s an example of what you might see:

Let’s walk through this screenshot.

1. I’ve navigated to a module directory. Here I’m checking the Countries module.
2. The alias I have set up for CodeSniffer, using custom Drupal rules, is drupalcs.
3. I want to test the file at tests/countries.test.
4. Sometimes this command can take a little while. If it seems like it’s hanging, especially if you’ve checked a directory, it may be too much, so try a single file at a time.
5. The first thing you’ll see is which file you checked, and the full path. Here, it’s /Applications/MAMP/htdocs/countries/tests/countries.test.
6. Next, you’ll see how many errors and warnings returned, and how many lines they affect. There can be multiple errors per line, and Coder will catch them all.
7. Next, each error or warning will be listed line by line.

I find it’s easiest to go in order from top to bottom, because sometimes one error causes others -- Coder can only understand so much -- so if you have, for example, an array that has one line indented improperly, it may also think the subsequent lines are indented improperly, even if they’re correct.

Our friends at Chromatic did a great post on PHP Codesniffer that walks you through more details.

Generally, you want to run Coder every time you make a change, and before you commit your code or submit a patch. This way, you’re always writing clean code, and anyone reviewing your code can concentrate on reviewing it for content, not style. Of course, everyone is human and we all make mistakes. Sometimes you’ll push up a tiny change without running Coder, and not realize there was a style issue. That’s why team code reviews are so important.

Team code reviews

If you are working with a team, you have another valuable tool in your arsenal. The most successful teams build in time to review one another’s code. There’s no substitute for code reviews by another person, and you should view them as an essential part of your process. The same is true for reviews on drupal.org as well. When planning time and resources for a project, make sure that there is time set aside for code reviews. When you’re working on contributed projects, make sure you take a look at issues marked "Needs Review" and test them. If you want a way to dive into a project, or just Drupal and contributed work in general, reviewing patches is a great way to get acclimated. You get exposed to other people’s code, and if you find something that needs to be corrected, that will stick with you and you’ll remember it.

Two things to remember when reviewing other people’s code, or when receiving reviews of your own:

1. Treat others as you would like to be treated. Be kind, courteous, respectful, and constructive. Be aware of your tone. It’s easy to come off more harshly than you intended, especially when working quickly. Take just a second to re-read your comments, especially if you’re communicating with someone you’re not acquainted with.
2. Take everything in stride, and don’t take it personally. Those reviewing your code want it to be good, and corrections aren’t a personal attack. This can be especially hard when you start out, but even after years, some comments might hurt your feelings. Don’t dwell on it! Thank them, make the corrections, submit the corrected code, and chances are, they’ll thank you, too.

Recap

Now you know what code standards are, why they’re important, and how you can get started implementing them in your code.

Further your understanding

• What IDE or Editor do you use for development? Are you able to configure it to work with Drupal's coding standards?
• Install PHP CodeSniffer and the Coder module and then run it on the files in either a custom module or one downloaded from Drupal.org. What, if any, violations did it point out?
• PHP CodeSniffer comes with two binaries, phpcs, and phpcbf. What does phpcbf do?

Additional resources

• Drupal Development Using PhpStorm (drupalize.me)
• Coder module (Drupal.org)
• PHP CodeSniffer (github.com)