<?xml version="1.0"?>
<document>

  <properties>
    <title>Gforge: PHP Coding Standards</title>
  </properties>

  <body>

<section name="Introduction">

<p>
Coding Standards.  Live them, love them.

<br/>
Then come up with a new introduction...
</p>
</section>
<section name="Comments">
<p>
<b>Guidelines</b>

<p/>
Non-documentation comments are strongly encouraged. A general rule of
thumb is that if you look at a section of code and think &quot;Wow, I don't
want to try and describe that&quot;, you need to comment it before you
forget how it works.

<ul>
  <li>C++ style comments (/* */) and standard C comments (//) are both acceptable.</li>
  <li>Use of perl/shell style comments (#) is prohibited.</li>
</ul>

<p/>
<b>PHPdoc Tags</b>

<p/>
Inline documentation for classes should follow the PHPDoc convention,
similar to Javadoc. More information about PHPDoc can be found here:

<p/>
<a href="http://www.phpdoc.de/">http://www.phpdoc.de/</a>

<p/>
<b>File Comments:</b> 

<p/>
Every file should start with a comment block describing its purpose,
version, author and a copyright message. The comment block should be a
block comment in standard JavaDoc format along with a CVS Id tag.
While all JavaDoc tags are allowed, only the tags in the examples
below will be parsed by PHPdoc. 
<p/>
GForge contains a mixed copyright. For files that have been changed 
since the GForge fork, the following header should be used:

<source><![CDATA[
/**
 *
 * brief description.
 * long description.  more long description.
 *
 * Portions Copyright 1999-2001 (c) VA Linux Systems
 * The rest Copyright 2002 (c) their respective authors
 *
 * @version   $Id: coding_standards.xml,v 1.1 2003/01/03 17:43:10 rspisser Exp $
 *
 */
]]></source>
<p/>
<b>Function and Class Comments:</b> 

<p/>
Similarly, every function should have a block comment specifying name,
parameters, return values, and last change date.

<p/>
<source><![CDATA[
/**
 * brief description.
 * long description.  more long description.
 *
 * @author    firstname lastname email
 * @param     variable  description
 * @return    value     description
 * @date      YYYY-MM-DD
 * @deprecated
 * @see
 *
 */
]]></source>

<p/>
<b>Note</b> 

<p/>
The placement of periods in the short and long descriptions is
important to the PHPdoc parser.  The first period always ends the
short description. All future periods are part of the long
description, ending with a blank comment line.  The long comment is
optional.
</p>
</section>

<section name="Formatting">
<p>
<b>Indenting</b>

<p/>
All indenting is done with TABS. Before committing any file to CVS, make sure
you first replace spaces with tabs and verify the formatting.

<p/>
<b>PHP Tags</b>

<p/>
The use of <code>&lt;?php ?&gt;</code> to delimit PHP code is
required.  Using <code>&lt;? ?&gt;</code> is not valid.  This is the
most portable way to include PHP code on differing operating systems
and webserver setups.  Also, XML parsers are confused by the
shorthand syntax.
</p>
</section>

<section name="Templating">
<p>
In the SourceForge system, PHP itself is used as the template
language.  To make the templating clearer, template files should be
separated out and included once objects and database results are
established. Detailed examples are in the docs repository and online
at:

<p/>
<a href="architecture/templating.html">Templating</a>

<p/>
Variables in the templates are presented surrounded by <code> &lt;?php ?&gt;</code> 
tags instead of the {} tags that some other template libraries would 
use. The end result is the same, with less bloat and more efficient code.
</p>
</section>

<section name="Expressions">
<p>

<ul>
  <li>Use parentheses liberally to resolve ambiguity. </li>
  <li>Using parentheses can force an order of evaluation. This saves the time a reader may spend remembering precedence of operators.</li> 
  <li>Don't sacrifice clarity for cleverness. </li>
  <li>Write conditional expressions so that they read naturally aloud.</li> 
  <li>Sometimes eliminating a not operator <code>(!)</code> will make an expression more understandable.</li> 
  <li>Keep each line simple. </li>
  <li>The ternary operator <code>(x ? 1 : 2)</code> usually indicates too much code on one line. <code>if... else if... else</code> is usually more readable. </li>
</ul>
</p>
</section>

<section name="Functions">
<p>
<b>Function Calls</b>

<p/>
Functions shall 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:

<p/>
<source><![CDATA[

$var = foo($bar, $baz, $quux);
]]></source>
<p/>
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:

<p/>
<source><![CDATA[

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

]]></source>

<p/>
<b>Function Definitions</b>

<p/>
Function declarations follow the unix convention:

<p/>

<source><![CDATA[
function fooFunction($arg1, $arg2 = '') {
    if (condition) {
        statement;
    }
    return $val;
}

]]></source>
<p/>
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:

<p/>
<source><![CDATA[
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;
}
]]></source>

</p>
</section>

<section name="Objects">
<p>
Objects should generally be &quot;normalized&quot; similar to a
database so they contain only the attributes that make sense.

<p/>
Each object should have Error.class as the abstract parent object
unless the object or its subclasses will never produce errors.

<p/>
Each object should also have a <code>create()</code> method which does
the work of inserting a new row into the database table that this
object represents.

<p/>
An <code>update()</code> method is also required for any objects
that can be changed.  Individual <code>set()</code> methods are
generally not a good idea as doing separate updates to each field in
the database is a performance bottleneck.

<p/>
<code>fetchData()</code> and <code>getId()</code> are also standard 
in most objects. See the tracker codebase for specific examples.

<p/>
Common sense about performance should be used when designing objects.

</p>
</section>

<section name="Naming">
<p>
<ul>

<li>Constants should always be uppercase, with underscores to separate
words. Prefix constant names with the name of the class/package they
are used in. For example, the constants used by the DB:: package all
begin with &quot;DB_&quot;.</li>

<li>True and false are built in to the php language and behave like
constants, but should be written in lowercase to distinguish them from
user-defined constants.</li>


<li>Function names should suggest an action or verb:
<code>updateAddress, makeStateSelector</code></li>

<li>Variable names should suggest a property or noun: <code>UserName,
Width</code></li>

<li>Use pronounceable names. Common abbreviations are acceptable as
long as they are used the same way throughout the project.</li>

<li>Be consistent, use parallelism.  If you are abbreviating number as
'num', always use that abbreviation.  Don't switch to using
<code>no</code> or <code>nmbr</code>.</li>

<li>
Use descriptive names for variables used globally, use short names for
variables used locally.
<p/>

<source><![CDATA[

$AddressInfo = array(...);

for($i=0; $i &lt; count($list); $i++)

]]></source>

</li>
</ul>

</p>
</section>

<section name="Control Structures">
<p>
These include if, for, while, switch, etc. Here is an example if
statement, since it is the most complicated form:

<p/>
<source><![CDATA[
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
]]></source>


<p/> 
Control statements shall have one space between the control
keyword and opening parenthesis, to distinguish them from function
calls.

<p/>
You should 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.

<p/>
For switch statements:

<p/>
<source><![CDATA[

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

]]></source>
</p>
</section>

<section name="Including PHP Files">
<p>
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.

Note: include_once and require_once are statements, not functions. You
don't need parentheses around the filename to be included, however you 
should do it anyway and use ' (apostrophes) not &quot; (quotes):

<p/>

<source><![CDATA[
include('pre.php');
]]></source>


</p>
</section>

</body>
</document>
