diff options
| -rw-r--r-- | pear/CODING_STANDARDS | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/pear/CODING_STANDARDS b/pear/CODING_STANDARDS new file mode 100644 index 0000000000..b0377cd2ab --- /dev/null +++ b/pear/CODING_STANDARDS @@ -0,0 +1,238 @@ +=========================================================================== +|| PEAR Coding Standards || +=========================================================================== + +$Id$ + +------------- +[1] Indenting +============= + +Use an indent of 4 spaces, with no tabs. If you use Emacs to edit PEAR +code, you should set indent-tabs-mode to nil. Here is an example mode +hook that will set up Emacs according to these guidelines (you will +need to ensure that it is called when you are editing php files): + +(defun php-mode-hook () + (setq tab-width 4 + c-basic-offset 4 + c-hanging-comment-ender-p nil + indent-tabs-mode nil)) + +Here are vim rules for the same thing: + + set expandtab + set shiftwidth=4 + set tabstop=4 + + +---------------------- +[2] 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; + + } + + +------------------ +[3] 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); + + +------------------------ +[4] Function 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; +} + + +------------ +[5] Comments +============ + +Inline documentation for classes should follow the PHPDoc convention, similar +to Javadoc. More information about PHPDoc can be found here: + + http://www.phpdoc.de/ + +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. + + +------------------ +[6] 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. + +Note: include_once and require_once are statements, not functions. You +don't need parentheses around the filename to be included. + + +----------------- +[7] 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. + + +------------------------- +[8] Header Comment Blocks +========================= + +All source code files in the core PEAR distribution should contain the +following comment block as the header: + +/* vim: set ts=4 sw=4: */ +// +----------------------------------------------------------------------+ +// | PHP version 4.0 | +// +----------------------------------------------------------------------+ +// | Copyright (c) 1997, 1998, 1999, 2000 The PHP Group | +// +----------------------------------------------------------------------+ +// | This source file is subject to version 2.0 of the PHP license, | +// | that is bundled with this package in the file LICENSE, and is | +// | available at through the world-wide-web at | +// | http://www.php.net/license/2_02.txt. | +// | If you did not receive a copy of the PHP license and are unable to | +// | obtain it through the world-wide-web, please send a note to | +// | license@php.net so we can mail you a copy immediately. | +// +----------------------------------------------------------------------+ +// | Authors: Original Author <author@example.com> | +// | Your Name <you@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. + +Files not in the core PEAR repository should have a similar block +stating the copyright, the license, and the authors. All files should +include the modeline comments to encourage consistency. + + +------------ +[9] CVS Tags +============ + +Include the <dollar>Id CVS vendor tag in each file. As each +file is edited, add this tag if it's not yet present (or replace existing +forms such as "Last Modified:", etc.). + +[NOTE: we have a custom $Horde tag in Horde cvs to track our versions +seperately; we could do the same and make a $PEAR tag, that would remain even +if PEAR files were put into another source control system, etc...] + + +----------------- +[10] Example URLs +================= + +Use "example.com" for all example URLs, per RFC 2606. + + +--------------------- +[11] Naming Constants +===================== + +Constants should always be uppercase, with underscores to seperate +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. |