Coding Standards

From ResourceSpace Documentation Wiki

Coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

Rule #1: If you have questions--ask!

Disclaimer

These coding standards are a work in progress. Many source code files in the repository may not comply with this document. Code clean-up is a work in progress (and a very good way to get involved in the project!).

Credits

Much of this documentation is based loosely on the PHP PEAR project documentation: http://pear.php.net/manual/en/standards.php

Compatibility

Functionality

Remember that Subversion is supposed to be live code -- keeping things up to date and ready to run at all times is our biggest method of quality control. Code must work at all times, except of course when it's broken by accident.

PHP 4 & 5

ResourceSpace maintains compatibility with PHP 4. All code submitted must be compatible with both PHP4 and PHP5

MySQL Strict Mode

Strict mode seems to be the default in most Windows MySQL installtions, as a result all code submitted should be compatible with MySQL strict mode. A development option exists to enable strict mode in ResourceSpace for development purposes. Developers are encouraged to enable this option in config.php.

Backward Compatibility

ResourceSpace maintains a backward compatibility policy that all code submitted should allows users upgrading to the next release to do so by replacing installed files with versions from the next release. See files in the dbstruct folder for more information on making additions to database files.

File Format

All files contributed to the repository should:

Be stored as ASCII text
Use UTF-8 character encoding
Mark line ends using the ASCII character LF
All interpreted files must end in .php

Coding Style

PHP Code Tags

Always use <?php and ?> to open and close sections of php code rather than short or asp style tags. This ensures broader compatibility across multiple systems.

Pages which produce no output do not need a closing ?> tag. Omitting the closing tag helps prevent unintentional white space being introduced.

Indentation

Use spaces to indent, not tabs. Indent size should be four spaces.

Please use Whitesmiths style indentation.

Line Length

There is no set limit for line length except concerning documentation blocks. Use your judgement based on the nature of the line and readability.

Control Structures

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated:

<?php
if ((condition1) || (condition2))
    {
    action1;
    } 
elseif ((condition3) && (condition4))
    {
    action2;
    } 
else
    {
    defaultaction;
    }
?>

You are strongly encouraged to always use curly braces even in situations where they are technically optional. Bracing all control structures increases readability and makes addition of any statments 'safe'.

Function Calls

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<?php
$var = foo($bar, $baz, $quux);
?>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, spaces may be inserted to promote readability:

<?php
$short          = foo($bar);
$long_variable  = foo($baz);
?>

Function Definitions

<?php
function fooFunction($arg1, $arg2 = '')
    {
    if (condition)
        {
        statement;
        }
    return $val;
    }
?>

Arguments with default values should be placed at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate.

Single vs. Double Quotes

Single quotes should be used in strings where variables are not involved as they are parsed marginally faster by the PHP interpreter.

<?php

$foo = 'This is a literal string';
$bar = "Foo is: $foo";

?>

MySQL statments

Mysql keywords in statements should be in all CAPITAL letters and all other identifiers should be in lowercase.

SQL statements may be split with the concatenation operator to increase readability. When splitting, the following line should be indented 1 space beyond the statement's opening brace:

<?php

$foo = sql_query('SELECT col1, col2, col3, col4 '.
                 'FROM table '.
                 'WHERE col1=value');

?>

Best practices

Readability of code blocks

Related lines of code should be grouped into blocks, seperated from each other to keep readability as high as possible. The definition of "related" depends on the code.

For example:

<?php

if ($foo)
    {
    $bar = 1;
    }

if ($spam)
    {
    $ham = 1;
    }

if ($pinky)
    {
    $brain = 1;
    }
?>

Return early

To keep readability in functions and methods, it is wise to return early if simple conditions apply that can be checked at the beginning of a method:

<?php
function foo($bar, $baz)
    {
    if ($foo)
        {
        //assume
        //that
        //here
        //is
        //the
        //whole
        //logic
        //of
        //this
        //method
        return $calculated_value;
        }
    else
        {
        return null;
        }
    }
?>

It's better to return early, keeping indentation and brain power needed to follow the code low.

<?php

function foo($bar, $baz)
    {
    if (!$foo)
        {
        return null;
        }

    //assume
    //that
    //here
    //is
    //the
    //whole
    //logic
    //of
    //this
    //method
    return $calculated_value;
    }
?>

Retrieved from "http://wiki.resourcespace.org/index.php/Coding_Standards"