diff options
Diffstat (limited to 'pear/CODING_STANDARDS')
| -rw-r--r-- | pear/CODING_STANDARDS | 254 |
1 files changed, 0 insertions, 254 deletions
diff --git a/pear/CODING_STANDARDS b/pear/CODING_STANDARDS deleted file mode 100644 index b9dd40f100..0000000000 --- a/pear/CODING_STANDARDS +++ /dev/null @@ -1,254 +0,0 @@ -=========================================================================== -|| 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 - (not - (and (string-match "/\\(PEAR\\|pear\\)/" (buffer-file-name)) - (string-match "\.php$" (buffer-file-name)))))) - -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; -} - -Functions should be named using the "studly caps" style (also referred to as -"bumpy case" or "camel caps"). The initial letter of the name is lowercase, -and each letter that starts a new "word" is capitalized. Some examples: - - connect() getData() buildSomeWidget() - -Private class members (meaning class members that an intented to be used -only from within the same class in which they are declared; PHP does not yet -support truly-enforceable private namespaces) are preceeded by a single -underscore. For example: - - _sort() _initTree() $_status - - ------------- -[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 expandtab tabstop=4 shiftwidth=4: */ -// +----------------------------------------------------------------------+ -// | PHP version 4.0 | -// +----------------------------------------------------------------------+ -// | Copyright (c) 1997, 1998, 1999, 2000, 2001 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. |