cvs: phpdoc /RFC coding_standards

philip Fri Jun 20 12:03:33 2003 EDT Modified files: /phpdoc/RFC coding_standards Log: A rewrite. Restructured current CS, and also added more information. Removed duplicate information already mentioned in the HOWTO or PEAR coding standard.

Index: phpdoc/RFC/coding_standards diff -u phpdoc/RFC/coding_standards:1.3 phpdoc/RFC/coding_standards:1.4 --- phpdoc/RFC/coding_standards:1.3 Sun Mar 31 16:42:53 2002 +++ phpdoc/RFC/coding_standards Fri Jun 20 12:03:33 2003 @@ -1,273 +1,251 @@ GENERAL: -Examples need to be clear and simple, but should -show the possibilities and usage of the function[s] -used. Only use OOP features where you would like to -present them, use simple functions in other areas. - -Do not take advantage of register_globals, just in -case you would like to present what register_globals -means. - -Make sure that the code won't produce any warnings -even with error_reporting = E_ALL. - - -HOWTO ADD EXAMPLES TO THE DOCS: - -1. Add PHP example code programlistings always with a role attribute set to - "php". Never add any other programlisting or PHP output with such a - role. It is reserved for PHP source code only. This role is used to - detect PHP code and highlight: - <programlisting role="php"> - -2. Title of examples: where appropriate use the function in the title, - e.g.: <title><function>array</function> example</title> - -3. The contents of examples with programlistings start on column 0 in the - XML code. - -4. All examples use the <?php ... ?> form instead of <? ... ?>. Use - <![CDATA[... ]]> for examples, since it eliminates the need to change < - to &lt;,etc. Examples look much better, and are easily manageable. - -5. Deprecated aliases and syntax should not be used in examples. - -6. If an example uses arguments specific to a newer version of PHP, it is - helpful to note this in the example: - foo("bar", "baz"); // second argument was added in PHP 4.0.3 +References: http://pear.php.net/manual/en/standards.php + http://www.php.net/manual/howto/ - If you use new vars (like $_ENV), always note that - from when they are available, and what to use in older - versions (always show newer and better examples too - by the side of older ones) - -7. The language constants true, false and null should be written as &true;, - &false; and &null;. In Examples write TRUE, FALSE, NULL. +Examples need to be clear and simple, but should show the possibilities and +usage of the functions used. Only use OOP features where you would like to +present them, use simple functions in other areas. -8. Never use tabs, not even in example program listings. XML should be - indented with one space character for each level of indentation; example - code uses four spaces. +Example guidelines: -9. Keep in mind: In <![CDATA[... ]]> sections nothing is parsed. So be sure - to put XML-code that needs parsing outside of CDATA sections, e.g. - dev-comments or links. Do not use any entities like &lt;. +0. Requirements + - Work with register_globals on or off + - When appropriate, use superglobals + - Never generate PHP errors (E_ALL friendly) + - Be short and generic + - Follow the PEAR coding standards + +1. Program listing roles (<programlisting role="xxx">) + + PHP examples should always have programlisting role="php" Only PHP + examples should have this role. Possible roles are: + + - c (C code) + - html (100% HTML) + - php (Some PHP) + - shell (commandline, bash, etc) + - sql (SQL statements) + +2. Titles + + When appropriate, it's encouraged to include the function name in + the title, for example: + + <title>A <function>strlen</function> example</title> + +3. Code placement + + The contents start at column/row 0 in the example. For example, this + means your example's content will be flush against the <![CDATA[ tag. + +4. PHP tags + + Always use long php tags (<?php) and never short tags (<? or <?=). + +5. CDATA + + Always use <![CDATA[ ... ]]> as this increases the readability of the + examples. For example, you literally write < instead of &lt; inside + of CDATA. Nothing in CDATA is parsed, it's taken literally. So, you + cannot use links, dev-comments, <function>, etc. + +6. Deprecated code + + Do not use aliases or deprecated syntax. + +7. Use of newer PHP features + + If an example uses features, such as arguments specific to a newer + version of PHP, add a comment that mentions this. For example: + + // Second argument was added in PHP 4.1.0 + foo('bar', 'baz'); + + If appropriate, show examples that work in older versions of PHP but + do not use reserved function names. For example, a PHP 4.2.3 version + of file_get_contents() should not be named file_get_contents(). + +8. Use of booleans in examples + + Do not use entities such as &true; in examples but instead write them + out as TRUE, FALSE, and/or NULL. + +9. Spacing + + Never use tabs, only use spaces. Intention levels are four spaces + and do not intent the first level of code. For example: + + Good: + ------------------------- + <?php + $str = 'Hello World'; + function foo($str) + { + return $str; + } + ?> + + Bad: + ------------------------- + <?php + $str = 'Hello World'; + function foo($str) + { + return $str; + } + ?> ERROR HANDLING -more to come??? - -Proper error handling, "... or die(...);" is good for development, -but useless for production. -Use some user defined exit function instead on error. -example: -$conn = mysql_connect($host, $user, $pass) -if (!$conn) { - doSomething(); - echo 'output stuff'; - exit; -} +This section isn't yet complete but there are three main ways to +implement error handling in the PHP manual: + a) Use of the 'or' operator. + + This is okay for development code but not ideal for production as use + of 'or' is rather limiting. An example use: + + foobar($lname) or die(...); + + b) A boolean check, along with {braces} + + This allows additional expressions inside the {braces} but requires + more code. This is the preferred method. An example use: + + if (!foobar($lname)) { + ... + exit; + } + + d) trigger_error() + + There is debate on whether to use trigger_error() in the examples fo for + now, do not use it (at least until the error handling docs are updated). ABOUT VARIABLES/CONSTANTS/STRINGS: -1. Don't use variable which are not set in examples. +1. Don't use variables which are not set in examples. 2. Constants should always be all-uppercase. -3. Use single qoutes ' where no metachars or variables need to be parsed. +3. Use single quotes ' when appropriate. -4. For output use echo, where adequate. +4. For output use echo, instead of print. 5. Lowercase html-tags. -6. Variables in Strings - -in discussion: - -echo "bar is $bar"; -vs. -echo 'bar is '.$bar; - -What about ${} and {$}??? +6. Variables in strings: -echo "this is ${bar}"; -echo "this is {$bar}"; -Hmm :) Variable variables come to mind but then again ${$var} can be seen -as a mix of both :) - -That is something indicates, why both works, and should work, and -why ${varname[1]} should not. But it works as you reported... Hm... - - -use ${varname} for complex vars in strings, $varname[x] -will confuse readers, as this is illegal outside strings, -concatenation makes code unreadable - -arrays in strings: - "a $arr[foo] b" - "a {$arr['foo']} b" - 'a ' . $arr['foo'] . ' b'; + Strings in strings + This is of course debatable and subject to personal preference. The + two main methods are inline or concatenation: + + echo "bar is $bar"; + echo "bar is {$bar}"; + echo "bar is ${bar}"; + vs + echo 'bar is ' . $bar; + + All of the above methods are acceptable. + + Arrays in strings + + As constants aren't looked for in strings, the following is fine + but may confuse newbies so it's not to be used in examples: + + echo "an $array[key] key"; + + Instead, consider these: + + echo "an {$array['key']} key"; + echo 'an ' . $array['key'] . ' key'; HOWTO WRITE... A: 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; - -} - +See PEAR coding standards B: FUNCTIONS: 1. FUNCTION NAMING: -Function names should always be all-lowercase.???? -If you need more than one word use foo_function() in functions defined in examples. +Procedural function names should be lowercase. If multiple words are +needed in the function name, use a _. Example: foo_function(); +OOP function names should follow the PEAR Coding Standards which +would be fooFunction(). 2. 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); - 3. FUNCTION DEFINITIONS -Function declaractions follow the "one true brace" convention: -function foo_function($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; -} - +See PEAR coding standards C: COMMENTS - -C style comments (/* */) and standard C++ comments (//) are both fine. -Use of Perl/shell style comments (#) is discouraged. -Do not use phpdoc (PEAR) comments, like @param. - -Suggestion: for single line comments use //, it seems to be more readable -to me than /* */ - D: EXAMPLE URLS/EMAIL -Use "example.com" for all example URLs, per RFC 2606. -Use sample email-adresses like joe@example.com -(someone pointed out the many junk mail coming -to birthdaygift@php.net and the like caused by an -example on the mail function page). - +See PEAR coding standards E: EXAMPLE PRINTOUTS -For short example printouts, use a C++ style comment -on the line where the output occurs, or the next line, -where it is needed: -echo $var; // outputs: 32 - -For longer example printouts use the screen -container in conjunction with <![CDATA[... ]]>: - <para> - This example would display: - <screen> -<![CDATA[ -a = orange -d = lemon -b = banana -c = apple -]]> - </screen> - </para> +For very short example printouts, use C++ style comment (//) on the +line where the output occurs, or in the description above the line: +echo $var; // 32 +For longer example printouts, there are a couple methods which are +acceptable. Medium sized output may be inline with the example +itself through use of /* comments */, for example: -COMPLETE EXAMPLE SKELETON +<?php +$arr = foo(); +print_r($arr); + +/* Outputs: -The screen section is optional. +Array +( + [0] => 'bread' + [1] => 'peanut butter' + [2] => 'jam' +) +*/ +?> + +For longer example printouts, use the <screen> container in conjunction +with <![CDATA[...]]> - <para> - <example> - <title><function></function> example</title> - <programlisting role="php"> +<para> + <example> + <title>A <function>foo</function> example</title> + <programlisting role="php"> <![CDATA[ <?php -your example code here -... +$arr = bar(); +print_r($arr); ?> ]]> - </programlisting> - <para> - The above example would produce the following output: - <screen> -<![CDATA[ -your long example output here -... -]]> - </screen> - </para> - </example> - </para> + </programlisting> + <para> + The output is: + </para> + <screen> +Array +( + [0] => 'a'; + [1] => 'b'; + [2] => 'c'; + ... +) + </screen> + </example> +</para> + + +COMPLETE EXAMPLE SKELETON + +See the HOWTO