Software Development

Your team must have a coding standard

This post uses PHP in examples, and links to existing code standards, but could easily apply to any language.
Every developer is different, and most believe that their way is THE way. Some have a Computer Science degree, some learnt on the job. Some have 20 years experience across multiple languages, while someone is on their first day with PHP as their first language. There are so many differences, but 1 commonality: shared code. Unless you run your own company, and will never have anyone edit your code, you need a standard so that all these different programmers with their diverse backgrounds are working in a common way.

The no standard situation

There are many ways to format PHP code. This flexibility is a good thing, but it can be abused. Let’s look at an utterly simplistic situation when developers format their code in different ways.

$someName = 'Bill'; $anotherName = 'Fred'; echo 'Hello '.$someName.' and '.$anotherName;

Done by a programmer A who obviously values screen space. Programmer B comes along. They have been asked to change and to &.

$someName = 'Bill';
$anotherName = 'Fred';
echo 'Hello '.$someName.' & '.$anotherName;

Change made, but B does not like the formatting so puts each statemenet on a seperate line. The code works as expected. Programmer C comes along. For gender equality Bill is now Jane.

$someName = 'Jane';
$anotherName = 'Fred';
echo "Hello $someName & $anotherName";

Programmer C makes the required change but believes double quotes are better than opening and closing single, so changes other parts of code.

This simple example may seem absurd, but unfortunately does have basis in reality. The time taken to reformat code in this example is very minor, but what about about a 300 line class with switches, nested if statements, and the next programmer does not like the brace style. The other issue is, could a bug have been accidentally introduced to previously working code? It would be safe to assume a workplace that allowed this would not be using unit tests.

Another example: spaces and tabs. Nesting your code makes it more readable, but how do you nest. Some like a tab, others some number of spaces.

function getMagicNumber ($inputVariable) {
    $coefficient = 0.150;
    $normalNumber = 10;
    if ($inputVariable * $coefficient > $normalNumber) {
        return $normalNumber * $coefficient;
    } else {
        return $normalNumber * ($coefficient + 0.1);
    }
}

The code works, however the word from above is that the coefficient is now 0.175. The easy ‘1 line change’ for programmer D. However they also decide to change tabs to 4 spaces.

function getMagicNumber ($inputVariable) {
    $coefficient = 0.175;
    $normalNumber = 10;
    if ($inputVariable * $coefficient > $normalNumber) {
        return $normalNumber * $coefficientt;
    } else {
        return $normalNumber * ($coefficient + 0.1);
    }
}

A bug was introduced. In this case it should be picked up by programmer D, but he is being lazy. The error is discovered later and given to programmer E. She reads the commit message (assuming they are using version control). Simple 1 line, but from a code diff (see below) nearly every line has changed, so it will require her to make some effort to find the error. Easy in this example, but in any case a waste of time, because D hit delete too many times while playing with code formatting, and didn’t fix it properly.

diff mn2.php mn1.php
2,8c2,8
< $coefficient = 0.175;
< $normalNumber = 10;
< if ($inputVariable * $coefficient > $normalNumber) {
< return $normalNumber * $coefficientt;
< } else {
< return $normalNumber * ($coefficient + 0.1);
< }
---
> $coefficient = 0.150;
> $normalNumber = 10;
> if ($inputVariable * $coefficient > $normalNumber) {
> return $normalNumber * $coefficient;
> } else {
> return $normalNumber * ($coefficient + 0.1);
> }

PHP coding standards

A good multi language code style survey is by Jari Aalto.

I am not going to say who is right, and which way is wrong in style. There is no exact answer to which is the best brace style to use, are underscore in variable names, how much code goes in a code file? Coders can and do debate coding styles, and often with considerable passion. However, within an organisation or project this is really a waste of precious developer time, and introduces a chance for bugs in good code. A standard needs to be chosen and agreed. Either an existing published standard or some variation. The important point is, that once chosen, all developers need to follow it.

The 2 best known coding standards for PHP are:

If either is followed, development is off to a good start.

Standard