******************************************************** 
 *    PHP Coding Standards for SuperAlberT.it           *
 *                                                      *
 *  Emiliano 'AlberT' Gabrielli                         *
 *                                                      *
 *  12/11/2001                                          *
 *                                                      *
 ******************************************************** 


These are the standards to be used in writing PHP scripts
for everyone who wants to contribute to SuperAlberT.it code.
Everyone who writes or modify a PHP script HAVE to do this
in accordance with this directives !!!


* Indenting

 Use an indentation of one tab, with no spaces. We suggest to
set the tab width of your editor to 4, but this is a choice
of yourself. Code alignment has to be achieved by use of spaces 
instead. This method allows both flexible and precise visualization.


* Control Structures

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


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


 Control statements should 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: 


switch (condition) {
    case 1:
        action1;
        break;
    case 2:
        action2;
        break;
    default:
        defaultaction;
        break;
}

* Function Calls

 Functions should 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: 
 

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


 As displayed above, there should 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: 


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


* Function and Class Definitions

 Function declaractions follow the "one true brace" convention: 


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: 

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;
}

Class declarations follow the same convenction. Here is an
example:

class fooClass()
{
    var bar;
    var _foo;
 
    function fooFunction($arg1, $arg2 = '')
    {
        if (condition) {
            statement;
        }
        return $val;
    }

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

Methods and Properties that are private must begin with an
underscore!


* Comments

 Non-documentation comments are strongly encouraged. A general
rule of thumb is that if you look at a section of code and
think "Wow, I don'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. 


* Including Code

 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(). 

Anywhere you are unconditionally including a file, use require_once().
Anywhere you are conditionally including a file (for example,
configuration parameters), use include_once(). 


* PHP Code Tags

 Always use <?php ?> to delimit PHP code, not the <? ?> shorthand.
This is required for PEAR compliance and is also the most
portable way to include PHP code on differing operating
systems and setups, it doesn't require to modify the standard
php.ini enabling shorthand. 

 
* Header Comment Blocks

 All source code files in all SuperAlberT.it projects should
contain the following comment block as the header: 


/* fileName.inc.php
*
* +----------------------------------------------------------------------+
* |                                                                      |
* | AlberT-Project: Description of the project                           |
* |                                                                      |
* +----------------------------------------------------------------------+
* |Copyright(c)SuperAlberT.it                                            |
* +----------------------------------------------------------------------+
* | This program is free software. You can redistribute it and/or modify |
* | it under the terms of the GNU General Public License as published by |
* | the Free Software Foundation; either version 2 of the License.       |
* +----------------------------------------------------------------------+
* | Authors: Emiliano Gabrielli <AlberT@SuperAlberT.it>                  |
* |          Your Name <youremail@example.com>                           |
* |                                                                      |
* +----------------------------------------------------------------------+
*
* $Id$
*/

 There's no hard rule to determine when a new code contributer
should be added to the list of authors for a given source
file. In general, their changes should fall into the "substantial"
category (meaning somewhere around 10% to 20% of code changes).
Exceptions could be made for rewriting functions or contributing
new logic. 

 Simple code reorganization or bug fixes would not justify
the addition of a new individual to the list of authors.


Emiliano Gabrielli  <AlberT@SuperAlberT.it>  12/11/2001