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

Chuck Hagenbuch wrote: > > 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. Agreed. I think it's harder to read code with 2, besides 4 is what PHP itself is using (although with tabs). No tabs is also good, Emacs users should be encouraged to set indent-tabs-mode to nil. > ---------------------- > [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; I disagree with this one. I find always using braces helpful because it makes it easier to add a new line, it makes debugging easier and it is more consistent. > 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 This is fine with me. > ------------------ > [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); No objections. > ------------------------ > [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. Also fine. The rule I have adhered to so far is to put the start brace on a separate line only if the indentation level is 0, which means in class or function (not method) definitions. But this format is fine also. > ------------ > [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/ May be worth mentioning that we don't ban C++ comments like the PHP source does. In PHP it is banned because some compilers allow it for C code, while others don't. > ------------------ > [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. People should be encouraged to use require_once wherever possible, which is anywhere you can say you want to parse this file unconditionally. > ----------------- > [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. This one is important. > ------------------------- > [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. This will obviously have to apply only for stuff in the main PEAR CVS repository. > ------------ > [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...] That'd be cool. What information could be interesting storing in extra CVS tags? > ----------------- > [10] Example URLs > ================= > > Use "example.com" for all example URLs, per RFC 2606. Didn't know there actually was an RFC for that. Heh. - Stig