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

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
    - vendor/symplify/coding-standard/packages/cognitive-complexity/config/cognitive-complexity-rules.neon

        max_cognitive_complexity: 8 # default

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:

# phpstan.neon
        max_cognitive_complexity: 50

Still 10 errors?

# phpstan.neon
        max_cognitive_complexity: 100

0 errors!

Great Job Done!

You can now add this to your .travis.yml or any other CI tools and make the PR merge and take a 2 weeks break.

Then decrease the criteria for 10 %:

# phpstan.neon
        max_cognitive_complexity: 90

and fix only 3-4 cases that will pop-up. One touch at a time. Then make a PR, merge & take a break again. "Rinse & Repeat".

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 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.

Enjoy the Massage!