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
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
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.
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:
tools can find and fix violations of standards like defined PSR, array
syntax, phpdoc formatting, naming conventions, logical operators spacing
The next step is to create custom-coding-standard.neon config file in your project root and include predefined rulesets.
From now on you are able to run checks using simple CLI commands:
vendor/bin/ecs check /path/to/project
Coding Standards without CI Are Useless
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:
- composer install --prefer-sourcescript:
- php vendor/bin/parallel-lint ./src ./tests
- php vendor/bin/ecs check ./src ./tests
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
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?
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
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
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
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?
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.
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.