The Boss vs. The Masseuse Way to Add Coding Standards to a Big Project

Found a typo? Edit me
This post was updated at February 2021 with fresh know-how.
What is new?

Use new Symplify 9 syntax for PHPStan rule registration.


Do you prefer a boss who's watching you how you sit at the desk telling how to sit right or a masseuse who's taking care of your hands tired from programming with her gentle hands?

When it comes to coding standards, the love and fun is the best experience with it. Let's look how such "masseuse" can be added to your big project.

"The Boss" Way to Add Coding Standard

It's very rare that projects have coding standards right from the first line. That applies to CI, tests, coverage, and docs. Why? They come with experience and with a need. The biggest added value of coding standards is to bring more fun to your team, as it works for you.

Saying that the most projects need and then add coding standards when they grow up to a large code base.

The most popularized way to do this is:

composer require squizlabs/php_codesniffer --dev
vendor/bin/phpcs --standard=PSR2 /app /src

I bet you're able to run these command even if you see it for the first time.

But what will happen next?

You'll get ~ X hundreds of errors you don't understand. It can feel embarrassing like having the boss' eyes on you all the time.

This is often the reason coding standard is not part of many great PHP projects, which makes me very sad.

"The Masseuse" Way to Add Coding Standard

How to make this first experience better? Start slowly, one touch at a time, like a masseuse with your hands.

1. Install Your Favoring Coding Standard Tool

For me, it's obviously ECS:

composer require symplify/easy-coding-standard --dev

2. Use One Sniff/Fixer that Helps You The Most

This is the most important step. This checker should be

3. Make it Pass Without Any Code Change

Last week a Cognitive Complexity Rule was published there was very positive feedback on it.

If your coding standard should have only 1 rule - this is the one.

# phpstan.neon
includes:
    - vendor/symplify/phpstan-rules/packages/cognitive-complexity/config/cognitive-complexity-services.neon

services:
    -
        class: Symplify\PHPStanRules\CognitiveComplexity\Rules\FunctionLikeCognitiveComplexityRule
        tags: [phpstan.rules.rule]
        arguments:
            maxMethodCognitiveComplexity: 8

But when you run your tool (vendor/bin/phpstan analyse /src), it will probably drop dozens of errors. And we don't want to go to the boss approach.


Saying that, we make the rule so free, that your code passes it:

 services:
     -
         class: Symplify\PHPStanRules\CognitiveComplexity\Rules\FunctionLikeCognitiveComplexityRule
         tags: [phpstan.rules.rule]
         arguments:
-            maxMethodCognitiveComplexity: 8
+            maxMethodCognitiveComplexity: 50

0 errors!

You can now add this to your GitHub Actions and make the PR. Merge it and take a 2 weeks break.


Then decrease the criteria for 10 %:

 services:
     -
         class: Symplify\PHPStanRules\CognitiveComplexity\Rules\FunctionLikeCognitiveComplexityRule
         tags: [phpstan.rules.rule]
         arguments:
-            maxMethodCognitiveComplexity: 8
+            maxMethodCognitiveComplexity: 45

When you feel ready, you can add 1 more checker, make a rule more strict... you get the idea to enjoy your massage :).

Proven Practice

This way I was able to add coding standards to quite a big codebase in Lekarna.cz a few years ago with not many troubles, and learn how they work along the way.


I wish you the same experience in your huge project.



Happy coding!


Have you find this post useful? Do you want more?

Follow me on Twitter, RSS or support me on GitHub Sponsors.