At Mollie we use PHP for our back-end code. Over the years the source code style that we used was primarily based on personal preferences of team members from days of yore. For example, tabs were used for indentation, and certain PHP constants like true, false and null were written in uppercase, and we had our own little rules about where the opening brace { should go.
It is required for every developer to use the Mollie PHP code style. This helps in understanding each other’s code (reduce cognitive load), and prevents reformatting code to match own personal preferences (and any debates about that!).
To aid in sharing a common code style, the code style settings of our IDE PHPStorm are added to VCS with each project. Additionally, we use PHP_CodeSniffer from Squiz Labs, a PHP tool to check PHP source code using a set of predefined rules. This tool can also be integrated into PHPStorm to give real-time feedback about the source code in your editor.
Unfortunately, learning our proprietary coding standard took a lot of time for new developers and wasted many hours in code reviews, hours that could have been spent discussing code design or delivering value to our customers. For this reason, we decided to switch to a more established coding standard.
Standards
In 2012 the PHP Framework Interop Group (FIG) accepted two coding standard recommendations: PSR-1 and PSR-2. The PSR-2 recommendation defines a “coding style guide”, and it extends the PSR-1 “basic coding standard”. The FIG is “a group of established PHP projects whose goal is to talk about commonalities between our projects and find ways we can work better together.” (quote from their website)
Many libraries and frameworks are already using the PSR-2 coding style guide, and new ones are adapting it as well. That means that a lot of developers are getting used to writing code using the PSR-2 style.
As a Mollie developer, if you are reading a lot of code written in the PSR-2 coding style, you also want to write code using it. New developers would also become more quickly acquainted with the Mollie codebase. So we decided to use PSR-2 for our complete code base instead of hanging on to our own proprietary coding style. But that meant that we had to convert all existing code to adhere to the recommendations of the PSR-2 spec. And of course we wanted to do that automatically.
Tooling
A couple of tools exist to format PHP source code. PHP_CodeSniffer has the PHP Code Beautifier and Fixer (phpcbf) that can format and fix some code styles changes. Another one is PHP-CS-Fixer by Fabien Potencier. This tool can use a format specification (like PSR-1/PSR-2), but you can also specify additional individual rules to be included or excluded during the formatting. After some tests we decided to use PHP-CS-Fixer on all of Mollie’s repositories, and use phpcbf to only fix the usage of tabs in places that PHP-CS-Fixer ignores.
The most important changes were the following:
After converting the code in a project all the unit and integration tests were run to check if nothing was broken. Next the changed files were committed using a different author than the person running the converter. We did this to distinguish the commit from other regular commits:
git commit --all --author="PSR-2 Mollie <codestyle@mollie.com>" -m "Convert to PSR-2"
Comparing code from previous commits (using for instance git blame) with the newly formatted PSR-2 code would of course show a lot of differences, even if you ignore whitespace. So we investigated if it was possible to convert all code from previous commits using the git filter-branch command.
With this command you can change each commit from the project history. So then you can format all code and commit it back into VCS. The downside is that each changed commit creates a new commit SHA-1 hash, which invalidates all cloned repositories. And each changed commit ideally needs to be checked with the tests. Reformatting thousands of commits would end up quite time consuming. These two arguments helped us decide not to change any code in repository's histories.
Results
The conversion created a bit of work for all team members with older local branches. They needed to merge the tooling, then run the reformatting on their branch and then finally merge the tip of the master into their branch.
But we are very happy with the end result. A standard and well-established code style between libraries and project code help developers understand code more quicker and reduce developers' cognitive load. New developers can get up-to-speed more quickly. More time is spent on discussing code design instead of the placement of braces.
