Coding Standards - Revisited
We first discussed coding standards back in 2011. A lot can happen in software in the space of four years, so we thought we’d take the opportunity to take a look at what’s changed since then. We’ll also go into some more detail on the coding standards we apply at Box UK, including the processes we use to ensure they are adhered to.
Since our previous blog post, The PHP Framework Interop Group have worked to produce various standards that have been adopted by many frameworks and libraries. PHP-FIG’s standards apply not only to coding style, but also to the structure of code for common functionality. For example, PSR-3 describes a common interface for logging libraries and PSR-4 outlines a specification for autoloading classes from file paths. This encourages code reuse and the development of framework-agnostic libraries. If you are going to implement something for which a PSR standard exists, following the PSR guidelines will mean that your code could be dropped in as a replacement for existing functionality in a wide range of frameworks and libraries, giving you a wider-audience for your library and improving its interoperability.
Due to the wide acceptance of PHP-FIG’s standards, we have also chosen to adopt them at Box UK. This includes following the PSR-2 coding style guide, rather than our own in-house style for PHP code. PSR-2 is a full coding style guide that extends the PSR-1) basic coding standard. PSR-1 sets out some general, easy to follow rules, such as enforcing the proper use of PHP tags and UTF-8 encoding. PSR-2 goes into more depth on the style in which code should be written. For example, PSR-2 specifies that four spaces should be used for indentation, and details exactly where opening and closing braces should be placed in different contexts.
The main benefit of following PSR-2 is that style of the PHP code we write is not only the same across our projects, but it is also consistent with the libraries we use that have adopted this standard (a great majority). This uniformity makes code more readable and maintainable. It also means that new developers are likely already familiar with our chosen style, as PSR-2 is generally considered to be the de facto standard for PHP code. There’s also the nice added bonus that PSR-2 support is built-in to PHP_CodeSniffer, which we continue to use to automate checking the style of our code.
For adapting old code to PSR-2 standards, Sensio Labs’ Coding Standards Fixer is a great tool which can automate much of this work for you. It’s worth doing this, particularly if you maintain a library that will be used by other developers.
As well as PHP_CodeSniffer for code style, we’re also using a number of other tools for checking our PHP code automatically:
- PHP Unit: for unit testing our PHP code
- PHP Mess Detector: for detection of suboptimal/overcomplicated code
- PHP Copy/Paste Detector: for detection of duplicate code
- Behat: to ensure that our code meets the requirements of our clients
JS Hint is preferred over JS Lint due to the fact that, at the time of writing, JS Lint’s ES6 support is limited. Also, some of the rules JS Lint forces you to follow are essentially related to style, rather than correctness. Using a combination of JSCS for style checking and JS Hint for problem detection gives us the flexibility to choose which style rules we’d like to follow:
crockford options are available as presets in JSCS, the latter essentially emulating the style checks carried out by JS Lint.
We’ve also started applying standards to our CSS files too. We lint our CSS with CSS Lint: When we’re using Less as a pre-processor to generate CSS, we’re using Less Lint instead. Similar libraries exist for linting SCSS files, such as SCSS Lint. There are Gulp equivalents available too, if you’re using that as a task-runner, instead of Grunt. Finally, we generate vendor-specific prefixes for our CSS rules automatically with Autoprefixer to ensure that our CSS will support whichever browsers we need it to.
These tools are all installable via NPM.
As we mentioned in 2011, “CI is a whole other blog post”, but I’ll cover some of what we’re doing here.
It’s all very well having all of these automated tools available to run against your code, but unless they are actually run on a regular basis, you won’t see the benefits. The best time to fix a problem is as soon as it occurs, before it gets into your main codebase: this is where CI comes in.
We previously used Jenkins CI for our continuous integration environment, but moved to Travis CI last year. The main driver for doing this was to remove the overhead of maintaining the CI server ourselves. As a hosted service using virtual environments that are instantiated and then destroyed, Travis removes this overhead. It is also well-integrated with GitHub, which we use for our source control.
For every pull request, we’re running the tools mentioned above against our code on Travis; code does not get merged and deployed until it passes these automated checks, plus a manual code review by other developers. Once the build has passed and any comments raised by the code review have been addressed, the code is released to a QA environment for testing by our QA team. Only after it has been tested to ensure it meets the acceptance criteria defined by our clients do we release code to our clients’ servers.
The concept of what coding standards are hasn’t really changed over the last few years, but where we choose to apply them and the technology we use to implement them has. A common set of standards has been widely adopted in the PHP community and it’s becoming more commonplace for emphasis to be placed on front-end standards too. The availability and ease of setup of great automated tools to check these standards has never been higher. If you’re not already applying standards on your project, try adopting them to reap the rewards of increased quality and maintainability that a good set of coding standards bring.