The Boss vs. The Masseuse Way to Add Coding Standards to a Big Project
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.
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.
How to make this first experience better? Start slowly, one touch at a time, like a masseuse with your hands.
For me, it's obviously ECS:
composer require symplify/easy-coding-standard --dev
This is the most important step. This checker should be
- easy to understand
- helpful for you as a programmer (not a
- helpful to your project
- and easy to fix code for you (like
If your coding standard should have only 1 rule forever and ever, this is the one. Let's try that one.
# ecs.yml services: Symplify\CodingStandard\Sniffs\CleanCode\CognitiveComplexitySniff: ~
But when you run your CS tool (
vendor/bin/ecs check /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:
# ecs.yml services: Symplify\CodingStandard\Sniffs\CleanCode\CognitiveComplexitySniff: maxCognitiveComplexity: 50
Still 10 errors?
# ecs.yml services: Symplify\CodingStandard\Sniffs\CleanCode\CognitiveComplexitySniff: maxCognitiveComplexity: 100
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 %:
# ecs.yml services: Symplify\CodingStandard\Sniffs\CleanCode\CognitiveComplexitySniff: maxCognitiveComplexity: 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 :).
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.
Enjoy the Massage!