TL;DR: For PHP, I suggest we write code in the style of PSR-1, PSR-2 and PSR-12.  It’s worth reviewing the standards every year.

Let’s get boring: coding standards.

There, I’ve said it.  

If you haven’t clicked away to Twitter or Instagram check Remedy tickets already, let me try to hook you with a reminder of a couple of aspects of programming life:

  • When you are tired or stressed, it’s good to be able fall back on a routine.
  • When you are tired or stressed, it’s nice not be surprised or frustrated.

In our shop, we write and read a lot of code written in PHP. This include many of our major systems from Drupal and WordPress to custom applications in Laravel.  

Some of this code is easy to read and modify, some not so much. So, anything that can make writing easier, and reading less surprising and less an exercise in puzzle solving makes life better.  It’s never fun picking up code you didn’t write, or you wrote years ago  when it contains odd indenting, capitalization, or idiosyncratic commenting patterns.

Because this is such a common problem as developers move from job to job,  widely adopted standards recommendations, such as PSR-1, PSR-2 and PSR-12 have been adopted in the the PHP world.

The PHP standards recommendations are all linked from https://www.php-fig.org/psr/

PSR-1 describes basic things like what character set your sources files should use, how to capitalize entities like namespaces, classes, functions, and methods, and how to structure logic and ‘side effects’.

PSR-12 (a draft standard recommendation to extend and replace PSR-2) is more broad.

From the document:

Like PSR-2, the intent of this specification is to reduce cognitive friction when scanning code from different authors. It does so by enumerating a shared set of rules and expectations about how to format PHP code. This PSR seeks to provide a set way that coding style tools can implement, projects can declare adherence to and developers can easily relate to between different projects. When various authors collaborate across multiple projects, it helps to have one set of guidelines to be used among all those projects. Thus, the benefit of this guide is not in the rules themselves but the sharing of those rules.

So, the Standards Recommendation documents set down rules for how our PHP code files should be structured, but what should WE do with them? Here are my suggestions:

  • First, review the documents every year.  You probably won’t retain everything the first time through, but read though them and note the parts you like and the parts that poke at your habits.
  • Second, try to make it automatic to actually do what the documents require.  For example, set your editors to always use Unix LF line endings, and use an indent of 4 spaces for each indent level. 
  • Look for tools that work with your development environment that will automatically flag or correct deviations from the standards. There are editor plugins, command line utilities, and git hooks that will flag or reject pushing non-complient code.  Try various tools to see what works for you.
  • Check the code you are working with right now and see how you can make it more compliant with the standards. 
  • When you are patching or updating PHP code, update the code to comply with PSR-12 as a regular part of your work.
  • If you really, really don’t like one of the recommendations, suggest that our group adopt an alternative recommendation.

Your future self will thank you for it. 🙂