This is the second post in a series about coding standards. In our first post, we talked about code standards and why they are so important. In this post, we’ll talk about how to implement Drupal coding standards in your projects.
Other posts in this series:
- Drupal Code Standards: What Are They?
- Drupal Code Standards: How Do We Implement Them?
- Drupal Code Standards: Formatting
- Drupal Code Standards: Documentation
- Drupal Code Standards: The t() function
- Drupal Code Standards: Object Oriented Coding & Drupal 8
- Drupal Code Standards: Twig in Drupal 8
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, we can always use a refresher. They’re also a living document, so there’s a good chance something may have been changed or added since the last time you gave them a go-over. Use this post as a reason to read them again! Make sure you have them bookmarked for reference, as well. https://www.drupal.org/coding-standards
Set up your editor 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.
Sublime Text
This post from Chris is a couple years old, and geared towards front-end developers, but has lots of great Sublime Text setup tips and plugins for every developer.
There’s some great info on drupal.org as well: https://www.drupal.org/node/1346890. 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!
PhpStorm
If you’re using PhpStorm, their website has extensive instructions for getting set up with Drupal configuration here.
If you’re using another editor, you can see if it’s listed here: https://www.drupal.org/node/147789
If not, I’d suggest googling it, and if you don’t find instructions, create them and add them to the list!
Review your own code - Use coder
The easiest way to make sure you’re conforming to coding standards is to use a program like 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.
- I’ve navigated to a module directory - here, I’m checking the countries module.
- The alias I have set up for codesniffer, using custom Drupal rules, is drupalcs.
- I want to test the file at tests/countries.test.
- 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.
- 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
- Next, you’ll see how many errors and warnings, and how many lines they affect - there can be multiple errors per line, and coder will catch them all.
- Next, each error or warning will be listed line by line.
I find it’s easiest to go in order, 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.
Christopher did a great post on PHP Codesnifffer last year, check it out here.
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 is reviewing it for content, and they don’t have to worry about 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 - make the time
The most successful teams build in time to review one another’s code. There’s no substitute for code reviews by another person, and making sure that you view them as an essential part of your process - the same goes for reviews on drupal.org. When planning time and resources for a project, make sure that there is time set aside for code reviews. When you’re working on contrib projects, make sure you take a look at issues marked "Need Review," and test them. If you want a way to dive into a project or just Drupal and contrib 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:
- 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.
- 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, and even after years, you can still get a comment that comes off in a way that hurts your feelings. Don’t dwell on it! Thank them, make the corrections, submit them, and chances are, they’ll thank you, too.
Now you know what code standards are, why they’re important, and how you can get started implementing them in your code. Set up your editor, install coder, and get ready for our next code standards post on formatting! We’ll talk about the nitty gritty of how you should format your Drupal code.
