2. Coding Standards

Our standards are heavily influenced by, and fully compatible with, the PEAR coding standards. We have adopted these standards because they are the most prevalent PHP coding standards in the industry.

All code must be fully compatible with PHP 5.1.4 up through the latest current version of PHP 5.2 at the time the code is written. All code must run without notices at the highest possible error reporting level (E_ALL | E_STRICT).

No exceptions are made to these rules under any circumstance unless very specific client demands require it. In that event, the project manager must explicitly approve the exceptions and they must be documented in detail.

Indenting: Use an indent of 4 spaces, with no tabs.

Line-length: Do not let line length exceed 100 characters.

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

<?php

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

?>

Control statements will have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

You are strongly encouraged to always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<?php

switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;
}

?>

Functions will be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:

<?php

$var = foo($bar, $baz, $quux);

?>

As displayed above, there will be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:

<?php

$short         = foo($bar);
$long_variable = foo($baz);

?>

Function declarations follow the "one true brace" convention:

<?php

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

?>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<?php

function connect(&$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;
}

?>

Inline documentation for classes must follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: PHP Doc

Non-documentation comments are generally required. A general rule of thumb is that if you look at a section of code and think "Wow, I do n't want to try and describe that", you need to comment it before you forget how it works.

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged.

Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file (for example, factory methods), use include_once. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once will not be included again by include_once.

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

In files that contain only PHP code, never include the closing tag. It can lead to whitespace being unexpectedly injected into the output and cause headers to be sent prematurely.

The exception to this rule will be in our MVC View templates in the framework. The view template files will use shorthand tags for brevity and readability. This is still portable because our View class automatically rewrites them to long tags using the streams layer before PHP interprets them.

2.9.1 Classes

Classes will be given descriptive names. Avoid using abbreviations where possible. Class names will always begin with an uppercase letter. Examples of good class names are:

• PostsController
• User

2.9.2 Class Methods

Methods will be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). Some examples:

• connect()
• getData()

Private and protected class methods are always preceded by a single underscore. For example:

• _sort()
• _initTree()

2.9.3 Class Properties

Class properties will be named using "studly caps" style.

Private and protected class properties are always preceded by a single underscore. For example:

• $this->_status

2.9.4 Class Constants

Constants will always be all-upercase, with underscores to separate words.

• BaseDB::ID_SZ
• DownloadController::MAX_PAGES

2.9.5 Variables

Local variables will be named using "studly caps" style.

• $localVariable

2.9.6 Constants

Constants will always be all-uppercase, with underscores to separate words. Constants will always be prefixed to avoid collisions in the global scope.

• MAD_BASE
• MAD_CONFIG_DIR

2.9.7 Functions

There are few (if any) reasons to write functions outside the scope of a class. Loose functions will be handled on a case-by-case basis.

2.9.8 Globals

Never use global variables. Period.