Coding guidelines

In an effort to make Grabbl's code more readable for ourselves (and others), we have adopted (are adopting) a couple of coding guidelines. It's not an official 'standard', we've just taken the good bits out of others.

Table of Contents

1. Indenting
2. Function and variable naming scheme
3. Class naming scheme
4. Function definitions
5. Function calls
6. Brackets, curly brackets and other little bits
7. Control structures
8. Comments
9. Conditional statements
10. End-note

Indenting

Indent using tabs. Use one tab per indentation.

Function and variable naming scheme

Variable and function names are always lowercase, except global variables. Names should be descriptive, but not too long. Multiple words are separated using _ (an underscore).
Functions usually do something, so try to use a verb in a function name when writing one.
Examples:

    <?php
    $table_size;
    load_template();
    ?>

An exception (mentioned earlier) applies to global variables. A global variable is a variable that might be used throughout the script (for instance inside functions, using the global keyword). Use uppercase letters for their names.

Class naming scheme

In contrast to functions and variable, classes should be named using UpperCamelCase.

Function definitions

When defining a function, keep in mind the naming scheme used in the previous section.
An example function definition could look like this:

    <?php
    function get_foo($argument, $default_argument = 'bar')
    {
        if($argument == 'foo')
        {
            $argument .= $default_argument;
        }
        return $argument;
    }
    ?>

For more details about the use of (curly) brackets, see section 5 (and maybe 6). The arguments of the function should follow the normal variable naming scheme. Multiple arguments must be separated by a comma and a space. The arguments that have a default value should be placed last.
The function should return something meaningful (at least true or false in order to indicate whether everything went fine). The return function may not used with brackets:
Wrong example:

    <?php
    return($val);
    ?>

It should also not contain another statement:
Another wrong example:

    <?php
    return $val+6;
    // OR
    return array($val, 'foo');
    ?>

Function calls

When calling a function, separate its parameters using a comma and a space. If one of the parameters is another function call, try to keep it readable. If that doesn't work out very well, consider using an extra variable instead.
Try to avoid spaces around the brackets surrounding the parameters.
Example:

    <?php
    $var = get_bar('this', 'function', 'call is', $long);
    get_foo($var);
    ?>

Brackets, curly brackets and other little bits

First the simple brackets ():
We generally use them without spaces around them.
Example:

    <?php
    get_foo($var);
    if($var == 'foo'); //...
    ?>

Curly brackets {} are important for readability and therefore get their own line. This mainly applies to control structures.
The curly brackets should be indented to the same level of their parent block.
Example:

    <?php
    if($val == true)
    {
        $random = rand();
        if($random != 4)
        {
            // Yeah well, you get the idea
        } 
    }
    ?>

The other little bits are mainly operators. Always place spaces around them.
Examples:

    <?php
    // Assignment operator
    $foo = $bar;
    // Test equal operator
    $foo == $bar;
    // Test not equal
    $foo != $bar;
    // Etc.
    ?>

AND, OR, && and the rest are also operators!

Control structures

The basic control structure guidelines are covered in the previous section. Keep in mind to use brackets well in complex conditional statements to avoid confusion about operator precedence (I personally don't really know which comes first... && or || or AND, and I don't care to find out either).
When using a switch, the following indentation applies:

    <?php
    switch($val)
    {
        case true:
            echo 'foobar';
            break;
        case false:
            // break intentionally omitted
        default:
            echo 'fubar';
            break;
    }
    ?>

Try to use a default: in your switches, unless it really gets in your way. Also, if you omit a break for some reason, mention that in a comment (so it is not mistaken for an error).
A note about for-loops: if you don't have a specific variable to count with, use a variable with a short name (like the common $i). Be careful when nesting; use a different variable for each loop (eg. start at $i and work your way through the alphabet).
A note about loops and if-blocks in general, don't nest too much. Too much nesting messes up readability. There is usually an alternative when you have many nested blocks.

Comments

We are using PHPDoc, so if you write a function, you probably want to write some instructions for the documentation. Use the Docblock style comments for these situations.
Multi-line comments and C++ style comments are fine, but don't use the Perl/Shell style.
Example:

    <?php
    /**
     * This could be a Docblock
     */
    // The C++ style comment is perfect for quick notes
    # This one is not OK!
    ?>

Conditional statements

Compare a value with a variable, not the other way around. Wrong:

    <?php
    if($variable == 'value'){
        // Blabla
    ?>

Correct:

    <?php
    if('value' == $variable){
        // Blabla
    ?>

This will prevent that, if you make the mistake of using = instead of ==, you will get stuck without any helpful error messages.

End-note

You can consider this file work-in-progress. Feel free to elaborate. :)