I have been working as a developer at Shopsys for 3.5 years now and this is my story of how I learned what coding standards are, how to use handy tools for automated standards, checks, and fixes, and how much harder it is to work on a project which lacks these things. In the article, I will also describe coding standards used in Shopsys Framework and introduce our package that covers multiple tools for fixing coding standards.
Working on a Project without Coding Standards
Last summer I started working on large scale Czech eCommerce site which was built on our earlier internal platform. The project has been in production for 6 years now and there have been more than 20 developers involved in its production, so you can probably imagine how much legacy code it gathered along the way. Many of the problems we encountered were caused by simple fact that there were no common standards for writing the code.
In one file you might see PHP along with HTML, CSS, and Javascript, as well as various naming conventions with lots of typos, weird indentations, and so on. Below is just an example of the sorts of errors that accrue when you have many lines of source code in one single file.
What you probably notice at first glance is that the code is quite complex and is not easy to read. In such cases, it is very difficult to focus on your day to day processes like writing new features, chasing bugs, and doing code reviews.
How to Use Handy Tools for Automated Standards Checks and Fixes
Luckily, there are tools that can help you with maintaining your coding style. All you need to do is require the coding standards package via composer:
composer require shopsys/coding-standards
The package provides commands that launch automated coding standards checks by 3 tools:
- PHP-Parallel-Lint (checks PHP files for valid syntax)
- and EasyCodingStandard package that encapsulates PHP_CodeSniffer and PHP-CS-Fixer
These tools can find and fix violations of standards like defined PSR, array syntax, phpdoc formatting, naming conventions, logical operators spacing etc.
The next step is to create custom-coding-standard.neon config file in your project root and include predefined rulesets.
# custom-coding-standard.neon
includes:
- vendor/symplify/easy-coding-standard/config/psr2-checkers.neon
- vendor/shopsys/coding-standards/shopsys-coding-standard.neon
From now on you are able to run checks using simple CLI commands:
vendor/bin/parallel-lint /path/to/project
vendor/bin/ecs check /path/to/project
--config=/path/to/project/custom-coding-standard.neon
Coding Standards without CI Are Useless
Sometimes it happens that you forget to run these commands before committing your code, but if you use a Continuous Integration tool, you can easily set it up to run the coding standards controls automatically after git push.
For example, in TravisCI you need to place a .travis.yml file with the following content into your project:
# .travis.yml
language: phpphp:
- 7.1
- 7.2install:
- composer install --prefer-sourcescript:
- php vendor/bin/parallel-lint ./src ./tests
- php vendor/bin/ecs check ./src ./tests
--config=custom-coding-standard.neon
This is great not just for you, but for all other project developers as well, because they can easily tell whether or not everything checks out with your code standards-wise, just by looking at the build result. This is very handy for code review, especially in terms of allowing the reviewer to focus on more important things than tabs and braces.
Coding Standard is Your Personal Guide from the Very First Step
I came into Shopsys when our ecommerce framework was in the early stages of development. At the time, it was only intended to be a newer version of our internal platform written from scratch using Symfony, and hadn’t yet reached the level of ambition and expertise which hallmarks the current Shopsys Framework. From the beginning I was amazed by the clean neat code which was being used by its developers, all the more so because it was a very large project. I was told that I should write code in the same style already in use, and before commiting the changes to run one simple command to see if anything was wrong with my code. If I had broken any rules, most of the the violations would be fixed automatically by using a similar command, simple enough even for a newbie like me to handle.
With automated tools you can get from malformatted code like this:
…to code with proper formatting, by using the simple command:
vendor/bin/ecs check ./src --fix
And the result?
This really helped me to get familiar with the coding style of the entire project, and thanks to these standards I was able to quickly learn on the fly.
Use Coding Standards Wherever You Can
Nowadays our main project — open source ecommerce Shopsys Framework — is decoupled into components and plugins, all of them following the same coding standards thanks to the package. In the example of the project I mentioned earlier, the package allowed me to amend parts which were messy and confusing, and helped me to unify the most problematic inconsistencies in the code.
Start with One Rule
It was impossible to apply all the rules at once, so I started with one simple rule — short array syntax. I required the package using composer, created my own configuration, and enabled the short array syntax, as seen below.
# custom-coding-standard.neon
checkers:
- PhpCsFixer\Fixer\ArrayNotation\ArraySyntaxFixer:
syntax: short
Running the vendor/bin/ecs check command fixed violations in 1076 files in no time and everyone was little bit happier as a result. I continued the cleaning process by adding more and more rules that we agreed on with the other developers in the team. This proves that adopting coding standards in your team can be done carefully step by step.
Where to Go Next?
It can happen, that none of the wide set of predefined standards fixers fulfills your specific needs. Luckily, you have the option of creating your own fixer and Tomáš Votruba has written two cool articles on this topic — How to write custom sniff for Code Sniffer and How to write custom fixer for php cs fixer.
Conclusion
To sum it up, developers’ work is much easier if they use the right tools, and this definitely includes automated coding standards checkers and fixers. It makes the learning process much smoother for new members of the team, helps to keep code consistent and easy to read, and last but not least, enables the team to focus on important issues during development and code review. It is always better to adopt the rules that make sense for your project, so I encourage you to go on our github and try the package for yourself.
If you want to see how thorough we are with coding standards and how using automated tools leads to readable and clean code, you can take a look. Thanks for reading, and we welcome any feedback you may have.
