Updated Coding Standard (markdown)

e107-Coding-Standard.md

@@ -4,10 +4,12 @@ IMPORTANT: This is a work in progress!
 # Section 1 - Pear Standard
 
 (Where no comment here, the Pear standard applies unmodified) The Pear coding standards (http://pear.php.net/manual/en/standards.php) form the basis of our own standard. This standard makes some comments on those standards, and in some cases defines a different way of doing things.
-Indenting
+
+### Indenting
 
 Use tabs to indent - not spaces - then you can adjust your editor to suit.
-Control Structures
+
+### 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.
 
@@ -41,8 +43,6 @@ Use BSD/Allman/Pascal style - opening '{' on a new line. The only exception is f
 
 
 # Section 2 - PHP/e107
-### Headers
-Every file must have one or two standard headers, as defined in Standard headers page
 
 ### Variables
 Use camelCase for variables.
@@ -71,7 +71,7 @@ Relative paths (e_XXX) to access files from within the code
 
     
 ### Forms
-Always use e107's form handler for form elements. 
+Always use e107's form handler for form elements in the front-end. 
 
     $frm    = e107::getForm();
     $frm->select($name,$value);
@@ -109,13 +109,11 @@ When passing more than three or so parameters to a function, consider passing so
     }
 
 Avoid replicating or bypassing e107 classes/handlers which are used for specific purposes.   
-eg. One example - use the file-class instead of PHP file functions to read directories.
+One example: use the e107 file-class instead of PHP file functions to read directories.
     	
     $fl = e107::getFile();  
     $filesArray = $fl->get_files($path, $fmask);
 
-Group functions which may be used in multiple areas of e107 into a class, and place the resulting 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 adding ANY new class/handler files to e107_handlers/ or a core plugin, be sure to discuss with the head developer of e107.**
-
 ### If/Else and Switch
 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:
@@ -165,7 +163,7 @@ Preferred version of above:
     $val = $array[$option];
 
 ### Extract
-Don't use extract() on arrays (usually DB rows) - it 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. 
+Avoid using extract() on arrays (usually DB rows) - it 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:**
 
@@ -201,20 +199,14 @@ Consider using list() instead of explode() when the values will be given their o
 
 As $_POST variables are checked/sanitized, create new variables to hold the checked values - makes it obvious what's safe and what's dodgy. (Note validator_class.php, especially where the same DB data can be input from several different places). Make sure $_POST variables are only processed if the user has the relevant permissions, and if the relevant options are enabled (its not enough to hide the button or field which initiates the post - security levels MUST be checked at the point of execution).
 
-Validate generated HTML on each page you work on to Html5.
+### Debugging/Errors
+Code must not produce any PHP warnings or notices during normal use. This primarily implies that all variables must be defined before being used. It also implies that a corrupted installation may produce errors, although as far as practicable the code should accommodate this. Many PHP notices can be avoided by using the functions vartrue() and varset() - see class2.php.
 
-Code must not produce any PHP warnings or notices during normal use. (This primarily implies that all variables must be defined before being used. It also implies that a corrupted installation may produce errors, although as far as practicable the code should accommodate this.
+We recommend this collection of [Firefox Addons](https://addons.mozilla.org/en-US/firefox/collections/camer0n/e107developer/). Most important being the _e107 Debugger_.  
 
-12. Where a feature is upgraded or changed:
-
-    For simple changes, the code should silently handle the situation
-    For more complex changes, an upgrade routine is required. See [plugin]_setup.php 
-
-
-
-Note SITEURLBASE to prepend to absolute links to get a full URL. Note SERVERBASE (2.0 only) to prepend to absolute links to get a full server filesystem reference
-
-14. To check whether a particular plugin is installed, use function e107::isInstalled($plugname) - returns TRUE if plugin installed. Alternatively, look at $pref['plug_installed'][plug_path'] ('plug_path' is the subdirectory name - e.g. calendar_menu). The array element exists only if the plugin is installed (assuming proper install/uninstall process followed), and contains the version number of the plugin.
+### Upgrades
+For simple changes, the code should silently handle the situation
+For more complex changes, an upgrade routine is required. See [plugin]_setup.php 
 
 ### Javascript, CSS and Meta
 Use the following functions to include js or css files
@@ -287,6 +279,14 @@ To avoid problems when 'STRICT' mode is set for MySQL, make sure any field which
 
 If reading XML files (typically plugin.xml) use the filter capability to limit the amount of data retained in memory to that which is actually needed.
 
+### Plugins
+Many of the plugins in the v2 branch have not yet been upgraded to the v2 way of doing things. 
+If you are developing a new plugin for v2+ of e107, be sure to use the following plugins as your reference of how things SHOULD be done. 
+
+* faqs - admin-area only
+* gallery - front-end and admin-area.
+
+To check whether a particular plugin is installed, use function e107::isInstalled($plugname) - returns TRUE if plugin installed. 
 
 ## Language Files and LANS
 
@@ -316,14 +316,19 @@ Avoid short language strings for words such as 'and', 'to' and so on. There aren
 
 ## Template Files
 
-(TODO v2.0 template standards)
+See the **gallery** plugin as a good reference. 
+Avoid code, especially functions, in template files
 
-
-1. Avoid code, especially functions, in template files
+## Html
+e107 v2+ uses the HTML5 standard. Be sure to validate the HTML output of your code.
+Many of us use the Firefox addon: http://users.skynet.be/mgueury/mozilla/ 
 
 
 ## Shortcodes
 
-1. Note and use the class-based structure introduced in v2.0 - with this it should be possible to totally avoid globals.
+1. Note and use the class-based structure introduced in v2.0 - with this it should be possible to totally avoid globals.See the **gallery** plugin for an example. 
 
 2. Parameter standards (see eHelper::scParams() and eHelper::scDualParams() )
+
+## Recommended Code Editors
+We recommend [Aptana Studio](http://www.aptana.com/products/studio3) as an editor. We may release e107-specific code-assistance in future.