Formatting code

Formatting

Annotations

All functions and methods should be annotated. Visit Comments and Annotations for more details on this topic.

Indentation

All code needs to be indented in multiples of four spaces, using the tab key not the space bar. This is to ensure consistency across IDEs and text editors. If the code spans multiple lines, make sure that the line is dropped and then indented.

<?php echo 'Bar'; ?>

<?php
    $foo = 'Foo';
    echo $foo;
?>

<?php
    function() {
        // some code
    }
?>

Spacing

Breathing room in and around functions/methods/classes

Before and after functions/methods/classes, there should be at least one empty line. Inside of functions/methods/classes, there should be an empty line before the closing curly brace and after the opening curly brace.

Bad practice:

function foo( $bar ){ // some code }
function foo2( $bar, $bar2 ) {
    // some code}
if( true ){// run something
}
Class Foo(){// some code}

Good practice:

function foo( $bar ) {

    // some code

}

function foo2( $bar, $bar2 ) {

    // some code

}

if ( true ) {

    // run something

}

Class Foo() {

    // some code

}

Parsed arguments and conditional statements

After the opening and closing parentheses, if there is an argument passed in, add a space to act as padding for the arguments. If there are multiple arguments, add a space after each separating comma. The opening curly braces should be on the same line as the function/conditional statement that requires them with a leading space.

Bad practice:

function foo($bar){

    // some code

}

function foo2($bar,$bar2)
{

    // some code

}

if(true){

    // run something

}

function no_args( ){

    // run something

}

Good practice:

function foo( $bar ) {

    // some code

}

function foo2( $bar, $bar2 ) {

    // some code

}

if ( true ) {

    // run something

}

function no_args(){

    // run something

}

Coding principles

jQuery no conflicts

All jQuery code must be wrapped in a no conflict. Examples of these are:

( function( $ ) {

    // Code goes here, using the jQuery $

} )( jQuery );

jQuery( function( $ ) {

    // Code goes here, using the jQuery $

} );

OOP (Object Orientated Programming)

Any custom plugins or extensions, written in either PHP or JavaScript, should be written following the OOP principles.

Even though OOP can seem excessive, this is to make sure that anything written fits in to the principles of being:

  1. Readable
  2. Scalable
  3. Maintainable

An example of a non-OOP code block:

function sliced_add_funds( $balance, $amount ) {

  $new_balance = $balance + $amount;
  return $new_balance

}

$balance = sliced_add_funds( 5, 25 );
echo $balance // prints 30 to the screen

and the same code, in OOP:

class Account {

    private $_balance;

    function __construct( $balance ) {

        $this->set_balance( $balance );

    }

    public function set_balance() {
        return $this->_balance;
    }

    public function get_balance() {
        return $this->_balance;
    }

    public function add_funds( $amount ) {

        $old_balance = $this->get_balance();

        $new_balance = $old_balance + $amount;

        $this->set_balance( $new_balance );

    }
}

$account = new Account( 5 );
$account->add_funds( 25 );

echo ( $account->get_balance() ); // prints 30 to the screen

Single responsibility principle

All functions, methods should follow the ‘single responsibility principal’ . If a function or method is carrying out multiple processes, split the processes in to multiple functions/methods and use an encapsulating function/method to call the overall process.

For example:

function withdrawMoney( $balance, $amount ) {

    // Remove parsed amount from the total balance
    $balance -= $amount;

    // If the balance is reduced below 0, apply a £5 fine
    if ( $balance < 0 )
        $balance -= 5;

    return $balance;

}

This should be split to reflect something more like this:

// remove parsed amount from the total balance
function removeFunds( $balance, $amount ) {

    $newBalance = $balance - $amount;

    return $newBalance;

}

// if the balance is below 0, add a fine
function checkFine( $balance ) {

    if ( $balance < 0 )
        $balance = $balance - 5;

    return $balance

}

// main function that calls other function to perform an action
function withdrawMoney( $balance, $amount ) {
    
    $newBalance = removeFunds( $balance, $amount );
    $newBalance = checkFine( $newBalance );

    return $newBalance;

}