Close

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.

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.

About the author

Chris Collins

Chris Collins

Chris Collins is a Principal Developer at Box UK. With a wide range of development experience, Chris is a keen advocate of the importance of testing and coding standards in delivering quality, maintainable software.

Comments

Gavin Davies

Jun 14th, 2011

You can use Netbeans with the Box UK coding standard, as Rod’s shown here. 1. Check out a copy of the BoxUK coding standard 2. Install BoxUK coding standard into your Sniffs. This is how I did it: gavd@gavd-desktop:/usr/share/php/PHP/CodeSniffer/Standards$ sudo ln -s /opt/BoxUK/codingstandards/PHP/ BoxUK 3. Install PHP-codesniffer plugin into NetBeans https://github.com/beberlei/netbeans-php-enhancements 4. Go into NetBeans options -> PHP -> should be a CodeSniffer tab. Select the “BoxUK” standard You should be able to then check files by right click->Show Code Standard Violations

Gavin Davies

Jun 19th, 2012

You no longer need to do the hoop jumping with symlinks, do this instead to get the Box UK coding standard: pear channel-discover pear.boxuk.net pear install boxuk/codingstandards

Gavin Davies

Jun 20th, 2012

I had problems with the gui for the codesniffer plugin for Netbeans. To get the current version of PHP Codesniffer plugin working with Netbeans 7.1.2, I had to manually edit the config: vim ~/.netbeans/7.1.2/config/Preferences/de/whitewashing/php/cs.properties Mine looks like: phpcs.codingStandard=BoxUK phpcs.customStandardPath=/opt/BoxUK/codingstandards/Php/ phpcs.shellScript=/usr/share/php/bin/phpcs phpcs.showWarnings=true

Jan 1st, 0001

Jan 1st, 0001

Add your comment

Related content

We're hiring. Let's talk. View available roles