Updated Coding Standard (markdown)

Coding-Standard.md

@@ -11,7 +11,7 @@ Control Structures
 
 Use BSD/Allman/Pascal style - opening '{' on a new line. The only exception is for short single statements within {...} such as ' return ; '- then it may be on a single line. This is optional.
 
-Good:
+**Good:**
 	
     if($t ==2)
     {
@@ -27,7 +27,7 @@ Good:
 	
     if($t == 2) { return; } // (Optional -for short lines only)
 
-Bad:
+**Bad:**
 
     if($t ==2) echo "hello"; // Missing braces { }
 
@@ -39,12 +39,7 @@ Bad:
 Routines are to be documented at both file and function level using phpDoc syntax. Where appropriate create supplementary pages of general documentation, and document individual variables.
 Headers
 
-Every file must have one or two standard headers, as defined in Stadard headers page
+Every file must have one or two standard headers, as defined in Standard headers page
-Error Handling
-
-At some point we will start using exceptions (*** TODO - DEFINE BETTER ***)
-Naming
-
 Basically as the standard:
 camelCase for variables
 UPPER_CASE_WITH_UNDERSCORES for constants
@@ -53,18 +48,18 @@ UPPER_CASE_WITH_UNDERSCORES for constants
     define("UPPERCASE_CONSTANT","value");
 
 
-## Section 2 - PHP/e107
+# Section 2 - PHP/e107
-### Language Files and LANS
+## Language Files and LANS
 
 Avoid duplicating terms, particularly in the admin area. If coding for admin, always search lan_admin.php and the lan_xxxx.php of the specific page you are working on for existing LANs which may match what you need translated. Avoid using HTML or Urls inside LAN definitions.
 
-Good:  
+**Good:** 
 
     define("LAN_XXX","Thank you [b]Firstname[/b]");
     define("LAN_XXX","Thank you [x]"); // Good - replace [ and ] with <a href='...'> and </a> using str_replace()
 
 
-Bad:  
+**Bad:**  
 
     define("LAN_XXX","Thank you <b>Firstname</b>"); //Bad contains HTML
     define("LAN_XXX","Thank you <a href='www.somewhere.com'>Firstname</a>"); //Bad contains HTML
@@ -78,34 +73,34 @@ Avoid short language strings for words such as 'and', 'to' and so on. There aren
     $text = str_replace($srch,$repl,LAN_EXAMPLE_01);
 
 
-### Programming detail
+## Programming detail
 Important: Some of these points related to form elements are deprecated in v2. Instead you should use the new form handler. `$frm->text()`, `$frm->selectbox()` etc. eg. input tags, select boxes etc.
 
-1. Where numeric values represent a particular status, define a constant for that value to make the meaning more obvious.
+### Constants
-	
+Where numeric values represent a particular status, define a constant for that value to make the meaning more obvious.
+    	
     define("CONSTANT","some value");
+    
+### Forms
+Always use e107's form handler for form elements. 
 
-2. Use double-quotes around html strings, unless the variable substitution capabilities or escape sequences are required (slightly faster).
+    $frm->select($name,$value);
+    $frm->checkbox($name,$value,$checked);
+     
+    
+### Globals
+Avoid the use of global variables, especially as an alternative to parameter passing. (We'll always need some globals - but the less there are, the smaller the chance of a clash). In v2.0 use the e107::getxxx syntax to get pointers to 'global' functions and objects like $sql, $tp
+    	
+    $pref   = e107::getPref();  
+    $sql    = e107::getDb();  
 
-	
+### Arrays    
-    echo "<input type='hidden' name='example' value='1' />";  
+When passing more than three or so parameters to a function, consider passing some of them in an array (especially convenient if many are optional) or if within a class, consider using vars.
-    echo "<input type='text' name='example2' value='".LAN_XXX."'  />"; //BAD - LANs may contain single-quotes.  
-    echo "<input type='text' name='example2' value=\"".LAN_XXX."\"  />"; //GOOD - single-quote safe.  
 
-
+### If/Else and Switch
-3. Within text strings enclosed in double quotes, use {...} round substituted variables (clearer, avoids variable names being misconstrued)
+Consider switch statements rather than multiple if...then...elseif.... (generally for three or more, or better yet, use an array to change the result where possible.
-	
-    echo "<input type='hidden' name='example' value='{$value}' />";
-
-4. Avoid the use of global variables, especially as an alternative to parameter passing. (We'll always need some globals - but the less there are, the smaller the chance of a clash). In v2.0 use the e107::getxxx syntax to get pointers to 'global' functions and objects like $sql, $tp
-	
-    $pref   = e107::getPref();
-    $sql    = e107::getDb();
-
-5. When passing more than three or so parameters to a function, consider passing some of them in an array (especially convenient if many are optional) or if within a class, consider using vars.
-
-6. Consider switch statements rather than multiple if...then...elseif.... (generally for three or more, or better yet, use an array to change the result where possible.
 Simple 'If/Else' example:
+
 	
     if($j == 3)
     {
@@ -115,15 +110,17 @@ Simple 'If/Else' example:
     {
         $text = "Goodbye";
     }
+
+
 Switch Example:
 
-	
+     
-    switch($option)
+     switch($option)
-    {
+     {
         case 'opt1':
          $val = "value1";
         break;
- 
+     
         case 'opt2':
          $val = "value2";
         break;
@@ -131,11 +128,12 @@ Switch Example:
         case 'opt3':
          $val = "value3";
         break;
- 
+     
         case 'opt4':
          $val = "value4";
         break;
-    }
+     }
+
 
 Preferred version of above:
 	
@@ -150,16 +148,18 @@ Preferred version of above:
 
 7. Group functions related to a particular area of e107 into a class, and place the resultant file into the e_HANDLER directory. Where there are 'admin' and 'user' functions, create an 'admin' class which is a descendant of the 'user' class to minimize memory usage in user mode. If the class contains admin functions only, either define the class within the admin file, or create a separate file within the admin directory. Before committing ANY new class/handler files to svn, be sure to check with the head developer of e107.
 
-8. Don't use extract() on arrays (usually DB rows) - causes confusion, and sometimes unneeded variables. And especially don't use it on $_POST and $_GET variables!
+8. Don't use extract() on arrays (usually DB rows) - causes confusion, and sometimes unneeded variables. And especially don't use it on $_POST and $_GET variables! Use the new _retrieve_ function to select and fetch data as an array. 
 
-Good:
+**Good:**
-	
-    while($row = $sql->db_Fetch(MYSQL_ASSOC)
-    {
-        $text .= $row['field_name'];
-    }
 
-Bad:
+    $sql = e107::getDb();
+    $array = $sql->retrieve('user', 'user_email, user_name', 'user_id=1');
+    
+    OR
+        
+    $array = e107::getDb()->retrieve('user', 'user_email, user_name', 'user_id=1');
+
+**Bad:**
 
     while($row = $sql->db_Fetch(MYSQL_ASSOC)
     {
@@ -192,29 +192,37 @@ Note SITEURLBASE to prepend to absolute links to get a full URL. Note SERVERBASE
     $frm->selectbox($name,$array);
 
 16. Where an appropriate handler exists, use it in preference to replicating or bypassing its functionality. eg. One example - use the file-class instead of PHP file functions to read directories.
-	
+
-    $fl = e107::getFile();
+    	
+    $fl = e107::getFile();  
     $files = $fl->get_files($path, $fmask);
 
-### SQL Details
+
+## SQL Details
 
 1. Don't enclose integer values in quotes in WHERE clauses - slows up the query. (But make sure there's no way the value can be something other than an integer).
 
     $sql->select('user','*',"user_id = '".$id."' LIMIT 1");	
     $id = 1;
-    $sql->db_Select_gen("SELECT * FROM `#user` WHERE user_id = '".$id."' LIMIT 1"); //BAD - Slower and risk of failure.
+
-    $sql->db_Select_gen("SELECT * FROM `#user` WHERE user_id = ".intval($id)." LIMIT 1"); //GOOD - Faster, 0 if no value
+    //BAD - Slower and risk of failure.
+    $sql->db_Select_gen("SELECT * FROM `#user` WHERE user_id = '".$id."' LIMIT 1"); 
+
+    //GOOD - Faster, 0 if no value
+    $sql->db_Select_gen("SELECT * FROM `#user` WHERE user_id = ".intval($id)." LIMIT 1"); 
+
 
 2. Where only one record is expected, use "LIMIT 1" in the query for better performance.
 
 3. insert() and update() Associate field names and values (rather than using an ordered list of just values) - avoids problems with DB changes. Make sure values are specified for any field without a default - else fails in STRICT mode.
+
 Insert Example:
 	
     $insert = array(
         'user_id' => 1,
         'user_email' => 'user@email.com'
     );
-
+    
     $sql->insert($insert);
 
 Update Example (many fields):
@@ -225,6 +233,7 @@ Update Example (many fields):
         // ... Long list of fields/values
         'WHERE' > 'user_id = 1'
     );
+    
     $sql->update($update);
 
 Update Example (few fields):
@@ -252,17 +261,17 @@ Note the _FIELD_DEFS and _NOTNULL arrays for assisting with producing valid data
 
 9. Consider using list() instead of explode() when the values will be given their own strings and the size of the array is known.
 
-Okay:
+**Okay:**
 	
     $tmp = explode("|",$array);
     $id = $tmp[0];
     $email = $tmp[1];
 
-Better:
+**Better:**
 	
     list($id,$email) = explode("|",$array);
 
-### Template Files
+## Template Files
 
 (TODO v2.0 template standards)
 
@@ -270,7 +279,7 @@ Better:
 1. Avoid code, especially functions, in template files
 
 
-### Shortcodes
+## Shortcodes
 
 1. Note and use the class-based structure introduced in v2.0 - with this it should be possible to totally avoid globals.