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
- easy to understand
- helpful for you as a programmer (not a
- helpful to your project
- and easy to fix code for you (like
3. Make it Pass Without Any Code Change
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
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 %:
# 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!