Before you dive into using coding standards it makes sense to understand exactly what they are and why they’re important, generally and specifically in the Drupal community. In this tutorial we will look at:
- What coding standards are
- Why following coding standards is a good idea
- Where coding standards come from
By the end of this tutorial you'll have a better understanding of what coding standards are, and why you should be adhering to them when you write code.
Goal
Learn what coding standards are and why you should follow them when writing code for Drupal projects.
Prerequisites
- None
Contents
What are coding standards?
Coding standards are a set of rules for programmers that lay out best practices, formatting, and various other rules. Think of it as the MLA style guide for programming. It tells us how to format what we write, so that everyone is using the same conventions.
Style
There are code standards that tell you how to style and format your code, which are mostly concerned with how it looks and how it will be read. This includes things like indentation, whitespace, and line length. Ensuring that all code adheres to the same style gives the whole Drupal project a sense of coherence, and makes it easier for developers to read other people’s code.
Substance
There are also code standards that inform the actual content and substance of your code. These standards include instructions for the use of various functions and components in your code. For example, making sure you use the translate function in certain scenarios, or, in PHP, using one specific function name when there are various aliases. Sizeof() and count() do the same thing and give us the same result - how do we know which to use? Coding standards can decide this for us, so that we know what to use, and what to expect.
Why are they important?
The point of a coding style standard is not to say one style is objectively better than another in the sense of the specific details (75 character and one-true-brace convention, for example). Instead, the point is to set up known expectations on how code is going to look.
Paul M. Jones, Why Coding Standards Matter
Keep code readable
When coding standards are followed, your code and your teammates’ code can be read the same way. You can review their code and know what to expect, and they can review yours. If you post a contrib module, someone from around the world can read, maintain, and modify your code. In a community like Drupal, this is essential.
Bridge the gaps for different backgrounds and languages
Drupal’s coding standards are based in English, and when working with a team from around the world, as is increasingly common today, standards can help reduce communication issues. Also, many programmers come to Drupal from a variety of programming language backgrounds, each with their own syntax and style. Having a concrete set of standards to look to helps keep our codebase consistent.
Automation
Code standards are especially important in Drupal documentation, because the API module automatically parses the information to generate documentation, which you can view at https://api.drupal.org/api/drupal. You can even set up your own API documentation site. The documentation is generated by the specific format of the comments, and uses a variety of tags in the source code (such as @param and @deprecated) to get detailed information about the code. We’ll go into documentation in more detail in another tutorial. If your code adheres to standards, you can check it with PHP_CodeSniffer, which can even be automated with Travis CI so that every pull request you make is checked for accuracy. The cleaner your code, the less work you have to do, and the more you can automate!
Who decides what coding standards are?
We do! Standards are decided by the Drupal community.
Drupal’s standards are based on the PEAR coding standards, but other than that, they are decided in an issue queue on Drupal.org. Someone brings up an issue, suggests a solution, the group talks it over, and when they come to a consensus, we’ve got a new standard.
Recap
In this tutorial we defined coding standards as a set of guidelines and conventions for how you write code. Coding standards guide both the style and substance of your code. There are tools for helping to automate the process of checking for coding standards violations. And agreeing on and adhering to a set of coding standards is important for teams of developers, or communities like Drupal, because it makes working with and talking about other people's code easier.
Further your understanding
- Do you, and your team if applicable, adhere to a set of coding standards? Which one?
- Can you give examples of how having a defined set of coding standards makes it easier for a team to do peer review of each other's code?
Additional resources
- Coding standards (Drupal.org) - The official Drupal coding standards.
- Why Coding Style Matters (smashingmagazine.com)
