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 <,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 <.
+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 < 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 [EMAIL PROTECTED]
-(someone pointed out the many junk mail coming
-to [EMAIL PROTECTED] 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
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
