What are coding standards and why should I care?

Part of delivering high quality code to our clients is ensuring consistency. It’s even more important if you work in a team because initially every member of the team has their own way of doing things.

Programming is a hard task, you have to keep in mind different perspectives on the problem you’re approaching: user experience, business goals, architectural goals and also the code. As the project becomes more complex and developers collaborate on more and more parts of code the number of errors can rise. Reading someone else’s code is like reading someone else’s handwriting; it’s doable but it’s one more hurdle you need to jump.

Coding standards to the rescue

Coding standard defines how you write your code. Code is a pretty rigid structure – not that different from grammar in a language – but there are still many ways how to write your code. Let’s examine that bit for a moment:

All the three blocks do the same thing – print the text barfoo on the screen if some variable equals to the text foo. But even though they do the same thing each of them looks different. Developers tend to be pattern-oriented. They are used to spot patterns and reuse existing pieces of code that fit that pattern.

if ($somevariable == “foo”)
echo ‘bar’ . $somevariable;

if ($some_variable == ‘foo’):
print “bar” . $some_variable;
endif;

if ($someVariable == ‘foo’) {
echo ‘bar’ . $someVariable;
}

Using a consistent way of writing blocks of code, frees developers mind from thinking about the form and allows them to focus on content.

Automation is a developer’s best friend

You can probably guess that having a dedicated employee to check if all the code matches the coding standard is not the right way to enforce coding standards. The following are tools that help us with the task. The most prominent one is PHP Code Sniffer (https://github.com/squizlabs/PHP_CodeSniffer). It is a command line tool that takes configuration in the form of XML file and returns either text results or another XML file for further parsing.

Checking your code is as simple as:

phpcs /path/to/code

What you get is a nice report of all the errors in files in the path

But even this is not ideal. You need to run the command every time you alter your code. That’s really annoying and you will probably give up after few hours of doing this. But there is another option – integrating PHP Code Sniffer into your IDE (Integrated Development Environment). There are integration packages for PHP Code Sniffer for most popular IDEs.

Setting up PHP Code Sniffer with PHPStorm

First you need to install phpcs (using composer)

composer global require “squizlabs/php_codesniffer=*”

Then open your PHPStorm, go to PHPStorm > Preferences > PHP > Code Sniffer and set the phpcs path. On my Mac it’s in /Users/tfejfar/.composer/vendor/bin/phpcs). Click Validate button to make sure everything works.

Now you can setup inspections for your files. In the Prefererences dialog go do Inspections and search for “sniff”. Under PHP > PHP Code Sniffer validation set check the checkbox on the right side of the list. Now set you severity settings to what you want. I personally set the “Severity” to Errors and select “Show warnings as Warning”, by default it’s weak warning. Also select your preferred coding standard – if the list is empty try the refresh button next to it. It should load all available standards. You can also select “Custom” and point PHPStorm to a directory where you have your config XML stored.

And that’s it. Your coding standards violations will now show as red underline immediately when writing code.

Summary

I hope this article helped you understand why coding standards are important. I suggest you start small if you’ve never used a coding standard before. If all your code is red, you’ll never fix it. There is also no chance that you will find the time and money to fix all your code at once.

First pick a coding standard that suits you. All new code will have to match it. But don’t start enforcing it in full from the beginning. Pick some basic rules and enforce them rigorously (See pear.php.net). Your codebase will gradually improve and when you feel comfortable add new rule and start fixing violations. That way you won’t be won’t be overwhelmed by the amount if violations and will keep fixing you code one step at a time.