eZ Community » Blogs » Arne Bakkebo » Code formatting standards - QA#2

By

Arne Bakkebo

Code formatting standards - QA#2

Thursday 07 March 2013 8:23:32 am

  • Currently 5 out of 5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

I'd like to start my quality software blog series with the basics, and talk a little about considerations around code formattings standards. I know that many already have a standard, and are using it consistently. I know also that many do not. In the eZ Publish part of Making Waves we have not been very consistent in this regard. I would like us to be.

[QA#1 - Quality software development introduction]

You might think that as a quality software development expert, your job is to write effective code. If you think so, you would be wrong. Your job is to write readable code. The code you write is not written for you, and it's purpose is not to be written. It's purpose is to be read. Mostly by anyone except you. Think about this for two seconds. Chances are that any code paragraph in your project will be read at least ten to twenty times more than it will be written during the full life of a project. Any time anyone need to understand what a module related to this code paragraph does, any bug relating to this code paragraph that need to be researched, and any bug fix someone need to apply. They read this code paragraph, trying to understand what it does. If it's well written they might be able to just skim it. If not, they may need to look at every line in excruciating detail, wasting hours and hours of time that could have been used on developing cool, new features.

Readable code also tend to be more bug free and stable. Firstly because the problems become more obvious, and the developer him/herself will easier notice them. But mainly because other developers will continue developing on top of your code, making bug fixes and extended functionality, and as the lifetime of the project progress without anyone keeping it clean the code will gain more entropy, becoming harder to work with and containing more bugs that need fixing. The result is very often that the project ends up in a quagmire where the developers spend more and more time bug fixing and less and less time actually writing better features.

The first line of defence in making readable code is to have a standard for how you format the code. It's not the only requirement, but it is an important first step. I do not really care what standards you choose. There have been flame wars for days and weeks and months on whether to place the starting curly brace on a new line or not. It's not important, most formatting conventions will take you about a day or two to get used to, should you choose to try, and the differences in actual productivity from one standard to the next is negligible. The important thing is to haveĀ  a standard, and to follow it consistently throughout your project and the company as a whole.

I still have two recommendations on choosing standards. Firstly, do not reinvent the wheel. Base your chosen format on an already existing standard with documentation. Secondly, for eZ Publish development I highly suggest using the formatting standard already existing for eZ Publish[1]. There are a number of reasons for this, which I will embellish on in the next paragraphs.

My main reason is that when developing in eZ Publish, we often grab code from eZ Publish to extend or modify it in some way. If you are not using the sameĀ  coding format as the code you are extending, you are bound to break the rule of code format consistency. And if you think you can manage to work your way around this problem, what about all the other people who are working on the same project as you? Or the people who will work on it long after you have moved on to your next project?

Secondly, following the eZ Publish standards will save you a bunch of argumentation time in discussions with the other people in your project and/or company. All developers have their own standards (or lack thereof) which they have habitually engraved in their soul through many years of development. Their standards will not match yours. They will have multiple more or less good arguments for using their formatting, like you will have multiple more or less good arguments for using yours. Avoid this irrelevant debate by using the formatting of the software you are building on.

Also, sooner or later, as a quality software developer, you will probably want to send eZ Systems a pull request to have your latest kernel bug fixed. Making pull requests to eZ Systems requires the code formatting standard defined for eZ Publish. Getting into the habbit of using it will simplify your life, as well as the life of everyone around you in the eZ community.

eZ Systems have a repository called eZCS[2], which is a set of configurations for PHP CodeSniffer[3]. It will validate your php/javascript/css code according to eZ Systems coding standards. In Making Waves we are currently working on scripts to automatically and continuously format the code as we develop. This has the advantage that everyone can be allowed to use their own formatting standards (or lack thereof) as they see fit, but the common code repository will still be conform and predictable to everyone else working on the project without much extra work. My colleague Konrad Dzwinel have set up a repository for this, called eZCodeValidator[4], since we have not been able to find anything like this. We have set this up to validate any files that are about to be committed to the git repository. If the validation is not accepted, the developer need to run a script to update the formatting of the same files, before being able to commit. By limiting us to only files we commit, we won't have to test and fix the whole repository at once, but over time the whole project will improve.

eZCodeValidator will currently validate and/or fix tabs vs.spaces and ending whitespace issues, but the thought is that it should do much more over time. What do you people think about this approach? Does anyone know any existing tools that can help with this?

References:

[1] eZ Publish coding standards: https://github.com/ezsystems/ezpublish-kernel/wiki/codingstandards
[2] eZ Systems code sniffer ruleset: https://github.com/ezsystems/ezcs
[3] PHP Code Sniffer: http://pear.php.net/package/PHP_CodeSniffer
[4] Automatic formatting scripts: https://github.com/makingwaves/eZCodeValidator

Proudly Developed with from