SourceForge: PHP Coding Standards $Id: coding_standards.html,v 1.3 2001/05/17 17:19:37 dbrogdon Exp $ SourceForge Engine Team [email] |
![]() |
Coding Standards. Live them, love them.
Then come up with a new introduction...
Guidelines
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.
PHPdoc Tags
Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here:
File Comments:
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. The following header should be used in all PHP files:
/** * * brief description. * long description. more long description. * * SourceForge: Breaking Down the Barriers to Open Source Development * Copyright 1999-2001 (c) VA Linux Systems * http://sourceforge.net * * @version $Id: coding_standards.html,v 1.3 2001/05/17 17:19:37 dbrogdon Exp $ * */ |
Function and Class Comments:
Similarly, every function should have a block comment specifying name, parameters, return values, and last change date.
/** * brief description. * long description. more long description. * * @author firstname lastname email * @param variable description * @return value description * @date YYYY-MM-DD * @deprecated * @see * */ |
Note
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.
Indenting
All indenting is done with TABS. Before committing any file to CVS, make sure you first replace spaces with tabs and verify the formatting.
PHP Tags
The use of <?php ?>
to delimit PHP code is
required. Using <? ?>
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.
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:
http://webdev.docs.sourceforge.net/architecture/templating.php
Variables in the templates are presented surrounded by <?php ?> 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.
(!)
will make an expression more understandable.
(x ? 1 : 2)
usually indicates too much code on one line. if... else if... else
is usually more readable.
Function Calls
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:
$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 Definitions
Function declarations follow the unix 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; } |
Objects should generally be "normalized" similar to a database so they contain only the attributes that make sense.
Each object should have Error.class as the abstract parent object unless the object or its subclasses will never produce errors.
Each object should also have a create()
method which does
the work of inserting a new row into the database table that this
object represents.
An update()
method is also required for any objects
that can be changed. Individual set()
methods are
generally not a good idea as doing separate updates to each field in
the database is a performance bottleneck.
Common sense about performance should be used when designing objects.
updateAddress, makeStateSelector
UserName,
Width
no
or nmbr
.
$AddressInfo = array(...); for($i=0; $i < count($list); $i++) |
These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated form:
if ((condition1) || (condition2)) { action1; } elseif ((condition3) && (condition4)) { action2; } else { defaultaction; } |
Control statements shall have one space between the control keyword and opening parenthesis, to distinguish them from function calls.
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.
For switch statements:
switch (condition) { case 1: { action1; break; } case 2: { action2; break; } default: { defaultaction; break; } } |
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 " (quotes):
include('pre.php'); |
Copyright © 1999, 2000, 2001 VA Linux Systems, Inc.