mirror/php-e107
1
0
Fork 0
mirror of https://github.com/e107inc/e107.git synced 2025-08-13 18:14:26 +02:00
Code Issues Releases Wiki Activity

Updated Coding Standard (markdown)

CaMer0n
2012-11-22 11:59:17 -08:00
parent c914381260
commit 5fa1018922
1 changed files with 66 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
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
Error Handling
At some point we will start using exceptions (*** TODO - DEFINE BETTER ***)
Naming
Every file must have one or two standard headers, as defined in Standard headers page
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
### Language Files and LANS
# Section 2 - PHP/e107
## 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();
echo "<input type='hidden' name='example' value='1' />";
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.
### Arrays
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.
3. Within text strings enclosed in double quotes, use {...} round substituted variables (clearer, avoids variable names being misconstrued)
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.
### 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:
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:
while($row = $sql->db_Fetch(MYSQL_ASSOC)
{
$text .= $row['field_name'];
}
**Good:**
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.