[Phpgroupware-cvs] [18509] update to reflect current requirements/practices

[Dave Hall]

Revision: 18509
          
http://svn.sv.gnu.org/viewvc/?view=rev&root=phpgroupware&revision=18509
Author:   skwashd
Date:     2008-03-24 22:06:35 +0000 (Mon, 24 Mar 2008)

Log Message:
-----------
update to reflect current requirements/practices

Modified Paths:
--------------
    trunk/phpgwapi/doc/coding_standard.txt

Modified: trunk/phpgwapi/doc/coding_standard.txt
===================================================================
--- trunk/phpgwapi/doc/coding_standard.txt      2008-03-19 13:40:16 UTC (rev 
18508)
+++ trunk/phpgwapi/doc/coding_standard.txt      2008-03-24 22:06:35 UTC (rev 
18509)
@@ -1,30 +1,32 @@
+phpGroupWare coding Standards
+
+Please comply with the following standard when working on phpGroupWare if you 
+want your patches accepted and modules included in supported releases.
+
 1)     Format your code so that we can read it, please!
 
 2)     Use tabs for formatting, NOT SPACES.  Tabs create smaller files and 
editors allow
-       developers to view a tab as however many spaces as they prefer.  Spaces 
do not allow this.
-       There is one exception (see #11 below).
+       developers to view a tab as however many spaces as they prefer - we use 
4 spaces.
+       Spaces do not allow this. There is one exception (see #11 below).
 
-3)     Use ' instead of " for strings.  This is a performance issue, and 
prevents
-       a lot of inconsistent coding styles.
+3)     Use ' instead of " for strings, where substitutions aren't required.  
This is a 
+       performance issue, and prevents a lot of inconsistent coding styles.  
When using 
+       substitutions, use curly braces around your variables - like so:
+       $var = "my_var: {$my_var}";
 
-4)     Comments go on the line ABOVE the code, NOT to the right of the code!
+4)     Comments go on the line ABOVE the code, NOT to the right of the code, 
unless it 
+       is very short.
 
-5)     For each section of code put a section divider with basic explanation 
of the following
-       code/functions.  It should look like this:
+5)     All functions and methods are to be documented using PhpDocumentor - 
http://phpdoc.org
 
-       
/****************************************************************************\
-       * These functions are used to pick my nose                              
     *
-       
\****************************************************************************/
-
 6)     Do not document every bit of code in comments.  PHP is an interpreted 
language and it will be
-       nasty on performance.
+       nasty on performance.  Provide enough information for someone else to 
understand your code.
 
-7)     Use switch statements where many elseif's are going to be used.  Switch 
is faster and I (who?) like it
-       better!
+7)     Use switch statements where many else if's are going to be used.  
Switch/case is faster
 
 8)     'If' statements need to use the following format:
 
-       if ($var == 'example')
+       if ( $var == 'example' )
        {
                echo 'This is only an example';
        }
@@ -37,26 +39,30 @@
 
        if ($var == 'example'){ echo 'An example'; }
 
+       or this
+       if ( $var = 'example')
+               echo "An {$var}";
+
        All other styles are not to be used.  This is it. Use it or I will 
personally come and nag you to
        death.
 
-9)     ALL 'if' statements MUST have matching { } (brackets).  Do NOT create 
'if' statements like this:
+9)     class/function format:
 
-       if ($a == b)
-               dosomething();
-
-       or:
-
-       if ($a == b) dosomething();
-
-       They make the code more difficult to read and follow.
-
-10)    class/function format:
-
-       class testing 
+       /**
+        * This class is for testing
+        *
+        * @package phpgroupware
+        * @subpackage module
+        * @category testing
+        */
+       class module_testing 
        {
-               function print_to_screen()
+               /**
+                * Output the value of $var the user
+                */
+               public function print_to_screen()
                {
+                       $var = phpgw::get_var('var', 'string', 'GET');
                        if ($var == 'example')
                        {
                                echo 'This is only an example';
@@ -68,7 +74,7 @@
                }
        }
 
-11)    Associative arrays must be written in the following manner:
+10)    Associative arrays must be written in the following manner:
 
        $array = array
        (
@@ -78,11 +84,14 @@
 
        Note that tabs are preferred around the '=>'.
 
-12)    Use the long format for <?php.  Do NOT use <?.
+11)    Use the long format for <?php.  Do NOT use <?.
 
-13)    All code should start with 1 tab.  Example:
+12)    All code should start with 1 tab.  Example:
 
 <?php
+/**
+ * PhpDoc page block here
+ */
        dosomething();
        if ($a)
        {
@@ -98,6 +107,27 @@
        dosomemorestuff();
 }
 
-14)    Use lower case for variable and function names.  No stubbly-case 
(mixed-case) code.
+13)    Use lower case for variable and function names.  No stubbly/mixed/camel 
case code.
 
-15)    Thanks for following these rules :)
+14)    All classes are to use the PHP5 OOP methods so they pass E_STRICT error 
+       reporting.  All instance variables are to be declared protected, unless 
+       private is really justified, the same goes for non public methods.  This
+       makes it easier to extend them in the future.
+
+15)    Classes are to be named <module_name>_<class_name> to prevent clashes - 
and
+       this is what createObject will expect.
+
+16) Always use symbol based comparison operators (&&, ||) instead of text based
+       operators (AND, OR) as they are evaluated in different orders and at 
different
+       speeds.  This is will prevent any confusion or strange results.
+
+17) You code must run with E_ALL error reporting turned on, E_NOTICES are 
ERRORS!
+       Where possible your code should run with E_STRICT error reporting.
+
+18) All variables, classes, methods, functions and comments must be in English.
+       Bad english is easier to work with than having to babelfish code to 
work out
+       how it works.
+
+19)    If you see code which doesn't comply with the above, please fix it :)
+
+Last Updated: $Id:$