Making a coding style guide

Mon 1 Aug 2022

Coding style guides have been around for a long time. They are crucial to creating great code when you have to work together with others. PHP knows some great examples already. PSR-12, slevomat, phpcompatibility and squizlabs are good resources when you want to make your own coding standard.

Why would you want to start your own standard? The reason we did this is to enhance our code in the first place. Secondly, we are dealing with some custom code that has been build a certain way. Running any standard against that codebase will gave mixed results. That's where some of these custom rules come in to play. Most of the time it is a collection of already existing rules and if in a collection disabling some. The important part of a coding standard is that it is doable with what you got.

PSR-12

This should be a golden standard for any PHP developer. Universally this standard is understood and accepted by the community at large. It is broadly ingrained in most tooling. For this reason developers should always strive to achieve PSR-12 as a minimum.

Writing the standard

Writing the standard to start with is an interesting process. You just run it against the codebase with some of the standards mentioned above. Then you ask yourself what the impact of some of these rules are and what they deliver. Based on that you can either include or ignore a certain rule.

Then when finished you let the team use the standard and gather feedback to finish up on that.

Process to change

Equally important is a process to go with this standard. There must be a mechanism in place to be able to bring proposals to the table to change the standard. Anybody who codes within the team can make proposals. Then, by fair vote, these get either accepted or rejected.

A standard should always be a process. Something that is subject to change. There needs to be dialog in the team on how to handle code. I've always found that the most healthy way to improve together.

Integrating code standard

You can even make this a step in the CI/CD pipeline to enforce that the coding standard is met. This is where this type of tooling is going to get you the most out of it. In most open-source projects this is already the golden standard for years. Behind company doors not so much. It is always a delight to see a process like this in place. It guides the developer to code according to the company standard.

Setting it up in a CI/CD process locks this standard in place. Making it harder for developers to publish code that is not up to standards.

TL;DR

I've never actually setup the full stack myself. Even when i've been using these tools for a long time. Most of the time these already existed and I could simply start using them. It has and will be interesting to see how this will evolve over time.