SourceForge: PHP Coding Standards $Id: coding_standards.html,v 1.3 2001/05/17 17:19:37 dbrogdon Exp $ SourceForge Engine Team [email]

0. Introduction

Coding Standards. Live them, love them.

Then come up with a new introduction...

1. Comments

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.

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

PHPdoc Tags

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

http://www.phpdoc.de/

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.

2. Formatting

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.

3. Templating

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.

4. Expressions

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

5. Functions

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

6. Objects

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.

7. Naming

• 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 "DB_".
• 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.
• Function names should suggest an action or verb: updateAddress, makeStateSelector
• Variable names should suggest a property or noun: UserName, Width
• Use pronounceable names. Common abbreviations are acceptable as long as they are used the same way throughout the project.
• Be consistent, use parallelism. If you are abbreviating number as 'num', always use that abbreviation. Don't switch to using no or nmbr.
• Use descriptive names for variables used globally, use short names for variables used locally.

$AddressInfo = array(...); for($i=0; $i < count($list); $i++)

8. Control Structures

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

9. Including PHP Files

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.