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.

What are coding standards?

Coding standards are guidelines for not only the syntactic structure and formatting of our code (no tabs, braces on new lines), but can also help shape the actual code we write (for example, rules like “don’t use global variables”, or “no singleton access”).

Why are coding standards important?

Enforcing standards for the code we write can guide us away from bad practices (such as antipatterns), warn us about possible mistakes (like assignments in conditionals), and a whole lot more.

Coding standards can be implemented in a number of ways, a few of which I’ll talk about in this post, but when you get going and couple this with a good Continuous Integration (CI) setup there really is no limit to where you can take it.

PHP

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:

All are easily installable via Composer, so it’s straightforward to add them to your project. The PHP QA Tools site contains links to all of these tools, as well as some other useful utilities.

Front-end Standards

In addition to our PHP standards, we’re also ensuring that the front-end aspect of our projects are up to scratch. This is particularly important when developing single-page applications, which are increasingly common today. In these cases, JavaScript is not there to add bells and whistles to your application – the front-end is a core part of your application. For us, this means ensuring we’re taking the same care with the JavaScript elements of our projects as we do with the PHP back-end code. We’re using a variety of tools in order to do this:

  • JavaScript Code Style: for checking the style of our JavaScript code
  • JS Hint: for detecting errors and potential problems in our JavaScript
  • Jasmine: for writing our JavaScript tests
  • Karma: for running our JavaScript tests

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: google and 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.

Continuous Integration

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.

Summary

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.

At Box UK we have a strong team of bespoke software consultants with more than two decades of bespoke software development experience. If you’re interested in finding out more about how we can help you, contact us on +44 (0)20 7439 1900 or email info@boxuk.com.

About the Author

Chris Collins

Principal Developer Chris has a wide range of experience in both back-end and front-end development, delivering high-profile projects for the likes of the BBC, The National Gallery and Investec Asset Management. Specialising in back-end PHP and database development, he is a keen advocate of the importance of testing and coding standards in developing quality software.