[PHP-CVS] cvs: php-src / CODING_STANDARDS
lsmith Sun Nov 11 16:29:54 2007 UTC Modified files: /php-srcCODING_STANDARDS Log: - migrate syntax to rEST to allow html/docbook rendering http://cvs.php.net/viewvc.cgi/php-src/CODING_STANDARDS?r1=1.36r2=1.37diff_format=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.36 php-src/CODING_STANDARDS:1.37 --- php-src/CODING_STANDARDS:1.36 Thu Dec 22 20:27:03 2005 +++ php-src/CODING_STANDARDSSun Nov 11 16:29:54 2007 @@ -1,6 +1,6 @@ -PHP Coding Standards - - + + PHP Coding Standards + This file lists several standards that any programmer, adding or changing code in PHP, should follow. Since this file was added at a very late @@ -9,37 +9,38 @@ well into the version 4 releases, many sections have been recoded to use these rules. - Code Implementation --- -[0] Document your code in source files and the manual. [tm] +0. Document your code in source files and the manual. [tm] -[1] Functions that are given pointers to resources should not free them +1. Functions that are given pointers to resources should not free them For instance, function int mail(char *to, char *from) should NOT free to and/or from. Exceptions: - - The function's designated behavior is freeing that resource. E.g. efree() - - The function is given a boolean argument, that controls whether or not -the function may free its arguments (if true - the function must free its -arguments, if false - it must not) - - Low-level parser routines, that are tightly integrated with the token -cache and the bison code for minimum memory copying overhead. - -[2] Functions that are tightly integrated with other functions within the +- The function's designated behavior is freeing that resource. E.g. efree() + +- The function is given a boolean argument, that controls whether or not + the function may free its arguments (if true - the function must free its + arguments, if false - it must not) + +- Low-level parser routines, that are tightly integrated with the token + cache and the bison code for minimum memory copying overhead. + +2. Functions that are tightly integrated with other functions within the same module, and rely on each other non-trivial behavior, should be documented as such and declared 'static'. They should be avoided if possible. -[3] Use definitions and macros whenever possible, so that constants have +3. Use definitions and macros whenever possible, so that constants have meaningful names and can be easily manipulated. The only exceptions to this rule are 0 and 1, when used as false and true (respectively). Any other use of a numeric constant to specify different behavior or actions should be done through a #define. -[4] When writing functions that deal with strings, be sure to remember +4. When writing functions that deal with strings, be sure to remember that PHP holds the length property of each string, and that it shouldn't be calculated with strlen(). Write your functions in a such a way so that they'll take advantage of the length property, both @@ -48,47 +49,47 @@ doing so, should return that new length, so it doesn't have to be recalculated with strlen() (e.g. php_addslashes()) -[5] NEVER USE strncat(). If you're absolutely sure you know what you're doing, +5. NEVER USE strncat(). If you're absolutely sure you know what you're doing, check its man page again, and only then, consider using it, and even then, try avoiding it. -[6] Use PHP_* macros in the PHP source, and ZEND_* macros in the Zend -part of the source. Although the PHP_* macro's are mostly aliased to the -ZEND_* macros it gives a better understanding on what kind of macro you're -calling. +6. Use ``PHP_*`` macros in the PHP source, and ``ZEND_*`` macros in the Zend +part of the source. Although the ``PHP_*`` macro's are mostly aliased to the +``ZEND_*`` macros it gives a better understanding on what kind of macro +you're calling. -[7] When commenting out code using a #if statement, do NOT use 0 only. Instead +7. When commenting out code using a #if statement, do NOT use 0 only. Instead use cvs username here_0. For example, #if FOO_0, where FOO is your -cvs user foo. This allows easier tracking of why code was commented out, -especially in bundled libraries. +cvs user foo. This allows easier tracking of why code was commented out, +especially in bundled libraries. -[8] Do not define functions that are not available. For instance, if a - library is missing a function, do not define the PHP version of the - function, and do not raise a run-time error about the function not - existing. End users should use function_exists() to test for the - existence of a function - -[9] Prefer emalloc(), efree(), estrdup(), etc. to their
[PHP-CVS] cvs: php-src / CODING_STANDARDS
jon Sun Nov 11 20:27:25 2007 UTC Modified files: /php-srcCODING_STANDARDS Log: s/Ident/Indent http://cvs.php.net/viewvc.cgi/php-src/CODING_STANDARDS?r1=1.37r2=1.38diff_format=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.37 php-src/CODING_STANDARDS:1.38 --- php-src/CODING_STANDARDS:1.37 Sun Nov 11 16:29:54 2007 +++ php-src/CODING_STANDARDSSun Nov 11 20:27:25 2007 @@ -181,9 +181,9 @@ of PHP or one of its standard modules, please maintain the KR style. This applies to just about everything, starting with indentation and comment styles and up to function declaration -syntax. Also see Identstyle_. +syntax. Also see Indentstyle_. -.. _Identstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html +.. _Indentstyle: http://www.catb.org/~esr/jargon/html/I/indent-style.html 3. Be generous with whitespace and braces. Keep one empty line between the variable declaration section and the statements in a block, as well as -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
helly Thu Dec 22 20:24:39 2005 EDT Modified files: /php-srcCODING_STANDARDS Log: - Point to README.TESTING http://cvs.php.net/viewcvs.cgi/php-src/CODING_STANDARDS?r1=1.34r2=1.35diff_format=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.34 php-src/CODING_STANDARDS:1.35 --- php-src/CODING_STANDARDS:1.34 Sat Nov 26 12:33:42 2005 +++ php-src/CODING_STANDARDSThu Dec 22 20:24:38 2005 @@ -161,7 +161,7 @@ Bad: 'foobar' 'foo_bar' - + Syntax and indentation -- @@ -207,6 +207,12 @@ indent preprocessor directives you should put the # at the beginning of a line, followed by any number of whitespace. +Testing +--- + +[1] Extensions should be well tested using *.phpt tests. REad about that +in README.TESTING. + Documentation and Folding Hooks --- -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
helly Thu Dec 22 20:27:04 2005 EDT Modified files: /php-srcCODING_STANDARDS Log: \# Damn ! http://cvs.php.net/viewcvs.cgi/php-src/CODING_STANDARDS?r1=1.35r2=1.36diff_format=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.35 php-src/CODING_STANDARDS:1.36 --- php-src/CODING_STANDARDS:1.35 Thu Dec 22 20:24:38 2005 +++ php-src/CODING_STANDARDSThu Dec 22 20:27:03 2005 @@ -210,7 +210,7 @@ Testing --- -[1] Extensions should be well tested using *.phpt tests. REad about that +[1] Extensions should be well tested using *.phpt tests. Read about that in README.TESTING. Documentation and Folding Hooks -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
helly Sat Nov 26 07:25:59 2005 EDT Modified files: /php-srcCODING_STANDARDS Log: - Synch with what we decided for 5 and what we are practicing since 5 http://cvs.php.net/diff.php/php-src/CODING_STANDARDS?r1=1.32r2=1.33ty=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.32 php-src/CODING_STANDARDS:1.33 --- php-src/CODING_STANDARDS:1.32 Fri Jan 30 05:15:24 2004 +++ php-src/CODING_STANDARDSSat Nov 26 07:25:58 2005 @@ -148,21 +148,21 @@ 'buildsomewidget' 'getI()' -[7] Classes should be given descriptive names. Avoid using abbreviations -where possible. Each word in the class name should start with a capital -letter, with words underscore delimited. The class name should be prefixed -with the name of the 'parent set'. +[7] Classes should be given descriptive names. Avoid using abbreviations where +possible. Each word in the class name should start with a capital letter, +without underscore delimiters (CampelCaps starting with a capital letter). +The class name should be prefixed with the name of the 'parent set' (e.g. +the name of the extension). Good: 'Curl' -'Foo_Bar' +'FooBar' Bad: 'foobar' 'foo_bar' 'FooBar' - - + Syntax and indentation -- -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
helly Sat Nov 26 07:33:43 2005 EDT Modified files: /php-srcCODING_STANDARDS Log: - Oversight http://cvs.php.net/diff.php/php-src/CODING_STANDARDS?r1=1.33r2=1.34ty=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.33 php-src/CODING_STANDARDS:1.34 --- php-src/CODING_STANDARDS:1.33 Sat Nov 26 07:25:58 2005 +++ php-src/CODING_STANDARDSSat Nov 26 07:33:42 2005 @@ -161,7 +161,6 @@ Bad: 'foobar' 'foo_bar' -'FooBar' Syntax and indentation -- -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
helly Fri Jan 30 02:01:26 2004 EDT Modified files: /php-srcCODING_STANDARDS Log: Newer compilers don't need this so many people don't know. Hence we make it a coding standard. http://cvs.php.net/diff.php/php-src/CODING_STANDARDS?r1=1.29r2=1.30ty=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.29 php-src/CODING_STANDARDS:1.30 --- php-src/CODING_STANDARDS:1.29 Mon Jan 26 07:37:48 2004 +++ php-src/CODING_STANDARDSFri Jan 30 02:01:25 2004 @@ -204,6 +204,9 @@ four spaces. It is important to maintain consistency in indenture so that definitions, comments, and control structures line up correctly. +[5] Precompiler statements (#if and such) MUST start at column one, you +cannot indent them. + Documentation and Folding Hooks --- -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-CVS] cvs: php-src / CODING_STANDARDS
The remark should note that developers should indent preprocessor (!) directives by putting the # at the beginning of a line, followed by any number of whitespace. - Sascha On Fri, 30 Jan 2004, Marcus Boerger wrote: helly Fri Jan 30 02:01:26 2004 EDT Modified files: /php-src CODING_STANDARDS Log: Newer compilers don't need this so many people don't know. Hence we make it a coding standard. http://cvs.php.net/diff.php/php-src/CODING_STANDARDS?r1=1.29r2=1.30ty=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.29 php-src/CODING_STANDARDS:1.30 --- php-src/CODING_STANDARDS:1.29 Mon Jan 26 07:37:48 2004 +++ php-src/CODING_STANDARDS Fri Jan 30 02:01:25 2004 @@ -204,6 +204,9 @@ four spaces. It is important to maintain consistency in indenture so that definitions, comments, and control structures line up correctly. +[5] Precompiler statements (#if and such) MUST start at column one, you +cannot indent them. + Documentation and Folding Hooks --- -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
helly Fri Jan 30 02:53:13 2004 EDT Modified files: /php-srcCODING_STANDARDS Log: Include Sascha's indendation hint http://cvs.php.net/diff.php/php-src/CODING_STANDARDS?r1=1.30r2=1.31ty=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.30 php-src/CODING_STANDARDS:1.31 --- php-src/CODING_STANDARDS:1.30 Fri Jan 30 02:01:25 2004 +++ php-src/CODING_STANDARDSFri Jan 30 02:53:12 2004 @@ -204,8 +204,9 @@ four spaces. It is important to maintain consistency in indenture so that definitions, comments, and control structures line up correctly. -[5] Precompiler statements (#if and such) MUST start at column one, you -cannot indent them. +[5] Precompiler statements (#if and such) MUST start at column one. To +indent preprocessor directives you should put the # at the beginning +of a line, followed by any number of whitespace. Documentation and Folding Hooks --- -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
wez Fri Jan 30 05:15:30 2004 EDT Modified files: /php-srcCODING_STANDARDS Log: word fix http://cvs.php.net/diff.php/php-src/CODING_STANDARDS?r1=1.31r2=1.32ty=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.31 php-src/CODING_STANDARDS:1.32 --- php-src/CODING_STANDARDS:1.31 Fri Jan 30 02:53:12 2004 +++ php-src/CODING_STANDARDSFri Jan 30 05:15:24 2004 @@ -204,7 +204,7 @@ four spaces. It is important to maintain consistency in indenture so that definitions, comments, and control structures line up correctly. -[5] Precompiler statements (#if and such) MUST start at column one. To +[5] Preprocessor statements (#if and such) MUST start at column one. To indent preprocessor directives you should put the # at the beginning of a line, followed by any number of whitespace. -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
sebastian Mon Jan 26 07:37:49 2004 EDT Modified files: /php-srcCODING_STANDARDS Log: Update URL. http://cvs.php.net/diff.php/php-src/CODING_STANDARDS?r1=1.28r2=1.29ty=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.28 php-src/CODING_STANDARDS:1.29 --- php-src/CODING_STANDARDS:1.28 Wed Jan 21 15:18:09 2004 +++ php-src/CODING_STANDARDSMon Jan 26 07:37:48 2004 @@ -183,7 +183,7 @@ indentation and comment styles and up to function declaration syntax. -(see also http://www.tuxedo.org/~esr/jargon/html/entry/indent-style.html) +(see also http://www.catb.org/~esr/jargon/html/I/indent-style.html) [3] Be generous with whitespace and braces. Always prefer: -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
helly Wed Jan 21 15:18:10 2004 EDT Modified files: /php-srcCODING_STANDARDS Log: All technical reasons that prevented us from studlyCaps are solved and all current extensions as well as the whole PEAR framework follow this rule. So for consistency i readd it. # Also we had the discussion onece and decided for this. # Lookup the archieves http://cvs.php.net/diff.php/php-src/CODING_STANDARDS?r1=1.27r2=1.28ty=u Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.27 php-src/CODING_STANDARDS:1.28 --- php-src/CODING_STANDARDS:1.27 Wed Dec 3 04:12:38 2003 +++ php-src/CODING_STANDARDSWed Jan 21 15:18:09 2004 @@ -133,7 +133,22 @@ [5] Variable names should be in lowercase. Use underscores to separate between words. -[6] Classes should be given descriptive names. Avoid using abbreviations +[6] Method names follow the 'studlyCaps' (also referred to as 'bumpy case' +or 'camel caps') naming convention, with care taken to minimize the +letter count. The initial letter of the name is lowercase, and each +letter that starts a new 'word' is capitalized. + +Good: +'connect()' +'getData()' +'buildSomeWidget()' + +Bad: +'get_Data()' +'buildsomewidget' +'getI()' + +[7] Classes should be given descriptive names. Avoid using abbreviations where possible. Each word in the class name should start with a capital letter, with words underscore delimited. The class name should be prefixed with the name of the 'parent set'. -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-CVS] cvs: php-src / CODING_STANDARDS
derick Wed Dec 3 04:12:39 2003 EDT Modified files: /php-srcCODING_STANDARDS Log: - I am sure I reverted this before Index: php-src/CODING_STANDARDS diff -u php-src/CODING_STANDARDS:1.26 php-src/CODING_STANDARDS:1.27 --- php-src/CODING_STANDARDS:1.26 Fri May 23 06:38:43 2003 +++ php-src/CODING_STANDARDSWed Dec 3 04:12:38 2003 @@ -133,22 +133,7 @@ [5] Variable names should be in lowercase. Use underscores to separate between words. -[6] Method names follow the 'studlyCaps' (also referred to as 'bumpy case' -or 'camel caps') naming convention, with care taken to minimize the -letter count. The initial letter of the name is lowercase, and each -letter that starts a new 'word' is capitalized. - -Good: -'connect()' -'getData()' -'buildSomeWidget()' - -Bad: -'get_Data()' -'buildsomewidget' -'getI()' - -[7] Classes should be given descriptive names. Avoid using abbreviations +[6] Classes should be given descriptive names. Avoid using abbreviations where possible. Each word in the class name should start with a capital letter, with words underscore delimited. The class name should be prefixed with the name of the 'parent set'. -- PHP CVS Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
