This post is the first in a series about Drupal coding standards - we’ll cover what they are, why they’re important, and go in-depth into a variety of topics in subsequent posts. Stay tuned for the rest of 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
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, and 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." http://paul-m-jones.com/archives/34
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 and maintain and modify your code. In a community like Drupal, this is essential.
Spend less time worrying about what your code looks like, and more time coding.
While researching this post, I saw so many arguments in articles and comments and issue queues about coding standards - whether they’re necessary, or restrictive. Probably hundreds if not thousands of hours spent going back and forth over them. While I’m sure the Drupal community spent a very long time deciding the Drupal standards, I’m happy that it’s done. They exist, and we as a community don’t have to spend time getting involved in discussions or arguments about their usefulness.
Help bridge the gap between coders of different backgrounds, languages, locations
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 documentation, because the API moduleautomatically parses the information to generate documentation, which you can view at http://api.drupal.org/. 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 a later post. 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? How are they decided?
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.
If you weren’t sure what coding standards are or why they are so important, I hope this post has given you a better understanding of their purpose and importance. The next post in this series will get you started with implementing Drupal coding standards in your projects.
Questions? Concerns? Arguments? Do you live for standards? Do you hate them? Let us know on twitter: @ChromaticHQ.
