Re: RE: [PHP-DEV] Re: [PHP-CVS] cvs: php4 /pear DB.php/pear/DB common.phpmysql.php

Quoting Sebastian Bergmann <sb@sebastian-bergmann.de>: > Yes, please post such a text on php-pear@ as some kind of RFC. Thanks. Okay - here is the Horde CODING_STANDARDS doc, edited for PEAR. =========================================================================== || PEAR Coding Standards || =========================================================================== $Id: horde/docs/CODING_STANDARDS,v 1.18 2000/09/19 17:45:23 bjn Exp $ ------------- [1] Indenting ============= Use an indent of 4 spaces, with no tabs. ---------------------- [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. In the case of an if with no else clauses, and only a 1 line action, the curly braces may be omitted: if (condition) action; or: if (condition) action; Whichever is more readable under the circumstances is preferred. For switch statements: switch (condition) { case 1: action1; break; case 2: action2; break; default: defaultaction; break; } // switch ------------------ [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. ------------ [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/ ------------------ [6] Including Code ================== If you are including a class, function library, or anything else which would cause a parse error if included twice, always use include_once. This will ensure that no matter how many factory methods we use or how much dynamic inclusion we do, the library will only be included once. ----------------- [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 PEAR distribution should contain the following comment block as the header: // +----------------------------------------------------------------------+ // | 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: PEAR.php.in,v 1.9 2000/10/15 09:02:54 ssb Exp $ 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. ------------ [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. -chuck -- Charles Hagenbuch, <chuck@horde.org> "If you can't stand the heat, get out of the chicken!" - Baby Blues