Recent changes to Coding Guidelines

Coding Guidelines modified by Sean Callaway

Sean Callaway — Fri, 28 Feb 2014 12:24:55 -0000

--- v3
+++ v4
@@ -1,12 +1,6 @@
 PEBDesk PHP Coding Guidelines
-
-
 ===

-
-
-
-
 This document is still under construction and is, by no means, complete.

 [TOC]
@@ -15,7 +9,7 @@

 ## Folder Structure and Organization

-From the root of the project, the following folders will exists:
+From the root of the project, the following folders will exist:

 * "includes" - for PHP include files
 * "script" - for JavaScript files
@@ -42,22 +36,22 @@
 In files that are pure PHP, the closing tag on a PHP document will be commented out.

 **INCORRECT:**
-:::PHP
-# 
-
-
-
-**CORRECT:**
-:::PHP
-# 
+~~~~
+
+~~~~~
+
+**CORRECT:**
+~~~~~
+
+~~~~~

 ## Class and Method Naming

@@ -66,45 +60,51 @@
 All other class methods should be entirely lowercased and named to clearly indicate their function, preferably including a verb. Multiple words should be separated with an underscore, and not CamelCased. Try to avoid overly long and verbose names.

 **INCORRECT:**
-:::PHP
-# class myclass 
-# class my_class
-
-**CORRECT:**
-:::PHP
-# class MyClass
-
-**INCORRECT:**
-:::PHP
-# function fileproperties()       // not descriptive and needs underscore separator
-# function fileProperties()       // not descriptive and uses CamelCase
-# function getfileproperties()    // Better!  But still missing underscore separator
-# function getFileProperties()    // uses CamelCase
-# function get_the_file_properties_from_the_file()    // wordy
-
-**CORRECT:**
-:::PHP
-# function get_file_properties()   // descriptive, underscore separator, and all lowercase letters
+~~~~~
+class myclass
+class my_class
+~~~~~
+
+**CORRECT:**
+~~~~~
+class MyClass
+~~~~~
+
+**INCORRECT:**
+~~~~~
+function fileproperties()       // not descriptive and needs underscore separator
+function fileProperties()       // not descriptive and uses CamelCase
+function getfileproperties()    // Better!  But still missing underscore separator
+function getFileProperties()    // uses CamelCase
+function get_the_file_properties_from_the_file()    // wordy
+~~~~~
+
+**CORRECT:**
+~~~~~
+function get_file_properties() // descriptive, underscore separator, and all lowercase letters
+~~~~~

 ## Variable Names

 The guidelines for variable naming is very similar to that used for class methods. Namely, variables should contain only lowercase letters, use underscore separators, and be reasonably named to indicate their purpose and contents. Very short, non-word variables should only be used as iterators in for() loops.

 **INCORRECT:**
-:::PHP
-# $j = 'foo';      // single letter variables should only be used in for() loops
-# $Str         // contains uppercase letters
-# $bufferedText        // uses CamelCasing, and could be shortened without losing semantic meaning
-# $groupid     // multiple words, needs underscore separator
-# $name_of_last_city_used  // too long
-
-**CORRECT:**
-:::PHP
-# for ($j = 0; $j < 10; $j++)
-# $str
-# $buffer
-# $group_id
-# $last_city
+~~~~~
+$j = 'foo';        // single letter variables should only be used in for() loops
+$Str           // contains uppercase letters
+$bufferedText      // uses CamelCasing, and could be shortened without losing semantic meaning
+$groupid           // multiple words, needs underscore separator
+$name_of_last_city_used    // too long
+~~~~~
+
+**CORRECT:**
+~~~~~
+for ($j = 0; $j < 10; $j++)
+$str
+$buffer
+$group_id
+$last_city
+~~~~~

 ## Commenting

@@ -112,43 +112,47 @@

 [DocBlock](http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock) style comments preceding class and method declarations so they can be picked up by IDEs:

-:::PHP
-# /**
-#  * Super Class
-#  *
-#  * @package  Package Name
-#  * @subpackage   Subpackage
-#  * @category Category
-#  * @author   Author Name
-#  * @link http://example.com
-#  */
-# class MyClass {
-
-:::PHP
-# /**
-#  * Encodes string for use in XML
-#  *
-#  * @access   public
-#  * @param    string
-#  * @return   string
-#  */
-# function xml_encode($str)
+~~~~~
+/**
+ * Super Class
+ *
+ * @package    Package Name
+ * @subpackage Subpackage
+ * @category   Category
+ * @author Author Name
+ * @link   http://example.com
+ */
+class MyClass 
+{
+~~~~~
+
+~~~~~
+/**
+ * Encodes string for use in XML
+ *
+ * @access    public
+ * @param     string
+ * @return    string
+ */
+function xml_encode($str)
+{
+~~~~~

 Use single line comments within code, leaving a blank line between large comment blocks and code.

-:::PHP
-# // break up the string by newlines
-# $parts = explode("\n", $str);
-# 
-# // A longer comment that needs to give greater detail on what is
-# // occurring and why can use multiple single-line comments.  Try to
-# // keep the width reasonable, around 70 characters is the easiest to
-# // read.  Don't hesitate to link to permanent external resources
-# // that may provide greater detail:
-# //
-# // http://example.com/information_about_something/in_particular/
-# 
-# $parts = $this->foo($parts);
+~~~~~
+// break up the string by newlines
+$parts = explode("\n", $str);
+
+// A longer comment that needs to give greater detail on what is
+// occurring and why can use multiple single-line comments.  Try to
+// keep the width reasonable, around 70 characters is the easiest to
+// read.  Don't hesitate to link to permanent external resources
+// that may provide greater detail:
+//
+// http://example.com/information_about_something/in_particular/
+$parts = $this->foo($parts);
+~~~~~

 ## Constants

@@ -169,91 +173,99 @@
 Use Allman-style indenting. Braces are always placed on a line by themselves and indented at the same level of the control statement that "owns" them.

 **INCORRECT:**
-:::PHP
-# function foo($bar) {
-#  // ...
-# }
-# 
-# foreach ($arr as $key => $val) {
-#  // ...
-# }
-# 
-# if ($foo == $bar) {
-#  // ...
-# } else {
-#  // ...
-# }
-# 
-# for ($i = 0; $i < 10; $i++)
-#  {
-#  for ($j = 0; $j < 10; $j++)
-#      {
-#      // ...
-#      }
-#  }
-
-**CORRECT:**
-:::PHP
-# function foo($bar)
-# {
-#  // ...
-# }
-# 
-# foreach ($arr as $key => $val)
-# {
-#  // ...
-# }
-# 
-# if ($foo == $bar)
-# {
-#  // ...
-# }
-# else
-# {
-#  // ...
-# }
-# 
-# for ($i = 0; $i < 10; $i++)
-# {
-#  for ($j = 0; $j < 10; $j++)
-#  {
-#      // ...
-#  }
-# }
+~~~~~
+function foo($bar) {
+   // ...
+}
+
+foreach ($arr as $key => $val) {
+    // ...
+}
+
+if ($foo == $bar) {
+   // ...
+} else {
+   // ...
+}
+
+for ($i = 0; $i < 10; $i++)
+   {
+   for ($j = 0; $j < 10; $j++)
+       {
+       // ...
+       }
+   }
+~~~~~
+
+**CORRECT:**
+~~~~~
+function foo($bar)
+{
+   // ...
+}
+
+foreach ($arr as $key => $val)
+{
+   // ...
+}
+
+if ($foo == $bar)
+{
+   // ...
+}
+else
+{
+   // ...
+}
+
+for ($i = 0; $i < 10; $i++)
+{
+   for ($j = 0; $j < 10; $j++)
+   {
+       // ...
+   }
+}
+~~~~~

 ## Bracket and Parenthetic Spacing

 In general, parenthesis and brackets should not use any additional spaces. The exception is that a space should always follow PHP control structures that accept arguments with parenthesis (declare, do-while, elseif, for, foreach, if, switch, while), to help distinguish them from functions and increase readability.

 **INCORRECT:**
-:::PHP
-# $arr[ $foo ] = 'foo';
-
-**CORRECT:**
-:::PHP
-# $arr[$foo] = 'foo'; // no spaces around array keys
-
-**INCORRECT:**
-:::PHP
-# function foo ( $bar )
-# {
-# 
-# }
-
-**CORRECT:**
-:::PHP
-# function foo($bar) // no spaces around parenthesis in function declarations
-# {
-# 
-# }
-
-**INCORRECT:**
-:::PHP
-# foreach( $query->result() as $row )
- 
-**CORRECT:**
-:::PHP
-# foreach ($query->result() as $row) // single space following PHP control structures, but not in interior parenthesis
+~~~~~
+$arr[ $foo ] = 'foo';
+~~~~~
+
+**CORRECT:**
+~~~~~
+$arr[$foo] = 'foo'; // no spaces around array keys
+~~~~~
+
+**INCORRECT:**
+~~~~~
+function foo ( $bar )
+{
+    //...
+}
+~~~~~
+
+**CORRECT:**
+~~~~~
+function foo($bar) // no spaces around parenthesis in function declarations
+{
+
+}
+~~~~~
+
+**INCORRECT:**
+~~~~~
+foreach( $query->result() as $row )
+~~~~~
+
+**CORRECT:**
+~~~~~
+foreach ($query->result() as $row) // single space following PHP control structures, but not in interior parenthesis
+~~~~~

 ## One Class Per File

@@ -272,16 +284,18 @@
 Always use single quoted strings unless you need variables parsed, and in cases where you do need variables parsed, use braces to prevent greedy token parsing. You may also use double-quoted strings if the string contains single quotes, so you do not have to use escape characters.

 **INCORRECT:**
-:::PHP
-# "My String"                                // no variable parsing, so no use for double quotes
-# "My string $foo"                           // needs braces
-# 'SELECT foo FROM bar WHERE baz = \'bag\''  // ugly
-
-**CORRECT:**
-:::PHP
-# 'My String'
-# "My string {$foo}"
-# "SELECT foo FROM bar WHERE baz = 'bag'"
+~~~~~
+"My String"        // no variable parsing, so no use for double quotes
+"My string $foo"       // needs braces
+'SELECT foo FROM bar WHERE baz = \'bag\''  // ugly
+~~~~~~
+
+**CORRECT:**
+~~~~~~
+'My String'
+"My string {$foo}"
+"SELECT foo FROM bar WHERE baz = 'bag'"
+~~~~~~

 ## SQL Queries

Coding Guidelines modified by Sean Callaway

Sean Callaway — Fri, 28 Feb 2014 11:46:39 -0000

--- v2
+++ v3
@@ -1,24 +1,19 @@
 PEBDesk PHP Coding Guidelines

+
 ===

+
+
 This document is still under construction and is, by no means, complete.

-
-
 [TOC]

-
-
 # Files and Folders

-
-
 ## Folder Structure and Organization
-
-

 From the root of the project, the following folders will exists:

@@ -30,10 +25,6 @@

 ## File Naming

-
-
-
-
 ### File Extensions

 All PHP pages will have the ".php" extension. All PHP include files will have the ".inc.php" extension. All PHP template files will have the ".tpl.php" extension.
@@ -46,3 +37,255 @@

 # PHP Coding Style

+## PHP Closing Tag
+
+In files that are pure PHP, the closing tag on a PHP document will be commented out.
+
+**INCORRECT:**
+:::PHP
+# 
+
+
+
+**CORRECT:**
+:::PHP
+# 
+
+## Class and Method Naming
+
+Class names will be CamelCased.
+
+All other class methods should be entirely lowercased and named to clearly indicate their function, preferably including a verb. Multiple words should be separated with an underscore, and not CamelCased. Try to avoid overly long and verbose names.
+
+**INCORRECT:**
+:::PHP
+# class myclass 
+# class my_class
+
+**CORRECT:**
+:::PHP
+# class MyClass
+
+**INCORRECT:**
+:::PHP
+# function fileproperties()       // not descriptive and needs underscore separator
+# function fileProperties()       // not descriptive and uses CamelCase
+# function getfileproperties()    // Better!  But still missing underscore separator
+# function getFileProperties()    // uses CamelCase
+# function get_the_file_properties_from_the_file()    // wordy
+
+**CORRECT:**
+:::PHP
+# function get_file_properties()   // descriptive, underscore separator, and all lowercase letters
+
+## Variable Names
+
+The guidelines for variable naming is very similar to that used for class methods. Namely, variables should contain only lowercase letters, use underscore separators, and be reasonably named to indicate their purpose and contents. Very short, non-word variables should only be used as iterators in for() loops.
+
+**INCORRECT:**
+:::PHP
+# $j = 'foo';      // single letter variables should only be used in for() loops
+# $Str         // contains uppercase letters
+# $bufferedText        // uses CamelCasing, and could be shortened without losing semantic meaning
+# $groupid     // multiple words, needs underscore separator
+# $name_of_last_city_used  // too long
+
+**CORRECT:**
+:::PHP
+# for ($j = 0; $j < 10; $j++)
+# $str
+# $buffer
+# $group_id
+# $last_city
+
+## Commenting
+
+In general, code should be commented prolifically. It not only helps describe the flow and intent of the code for less experienced programmers, but can prove invaluable when returning to your own code months down the line. There is not a required format for comments, but the following are recommended.
+
+[DocBlock](http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock) style comments preceding class and method declarations so they can be picked up by IDEs:
+
+:::PHP
+# /**
+#  * Super Class
+#  *
+#  * @package  Package Name
+#  * @subpackage   Subpackage
+#  * @category Category
+#  * @author   Author Name
+#  * @link http://example.com
+#  */
+# class MyClass {
+
+:::PHP
+# /**
+#  * Encodes string for use in XML
+#  *
+#  * @access   public
+#  * @param    string
+#  * @return   string
+#  */
+# function xml_encode($str)
+
+Use single line comments within code, leaving a blank line between large comment blocks and code.
+
+:::PHP
+# // break up the string by newlines
+# $parts = explode("\n", $str);
+# 
+# // A longer comment that needs to give greater detail on what is
+# // occurring and why can use multiple single-line comments.  Try to
+# // keep the width reasonable, around 70 characters is the easiest to
+# // read.  Don't hesitate to link to permanent external resources
+# // that may provide greater detail:
+# //
+# // http://example.com/information_about_something/in_particular/
+# 
+# $parts = $this->foo($parts);
+
+## Constants
+
+Constants follow the same guidelines as do variables, except constants should always be fully uppercase. This includes built-in constants, like TRUE, FALSE, and NULL.
+
+## Logical Operators
+
+A space should always precede and follow **!**.
+
+## Whitespace in Files
+
+No whitespace can precede the opening PHP tag or follow the closing PHP tag (which should be commented out anyway).
+
+Use tabs for whitespace in your code, not spaces. This may seem like a small thing, but using tabs instead of whitespace allows the developer looking at your code to have indentation at levels that they prefer and customize in whatever application they use.
+
+## Code Indenting
+
+Use Allman-style indenting. Braces are always placed on a line by themselves and indented at the same level of the control statement that "owns" them.
+
+**INCORRECT:**
+:::PHP
+# function foo($bar) {
+#  // ...
+# }
+# 
+# foreach ($arr as $key => $val) {
+#  // ...
+# }
+# 
+# if ($foo == $bar) {
+#  // ...
+# } else {
+#  // ...
+# }
+# 
+# for ($i = 0; $i < 10; $i++)
+#  {
+#  for ($j = 0; $j < 10; $j++)
+#      {
+#      // ...
+#      }
+#  }
+
+**CORRECT:**
+:::PHP
+# function foo($bar)
+# {
+#  // ...
+# }
+# 
+# foreach ($arr as $key => $val)
+# {
+#  // ...
+# }
+# 
+# if ($foo == $bar)
+# {
+#  // ...
+# }
+# else
+# {
+#  // ...
+# }
+# 
+# for ($i = 0; $i < 10; $i++)
+# {
+#  for ($j = 0; $j < 10; $j++)
+#  {
+#      // ...
+#  }
+# }
+
+## Bracket and Parenthetic Spacing
+
+In general, parenthesis and brackets should not use any additional spaces. The exception is that a space should always follow PHP control structures that accept arguments with parenthesis (declare, do-while, elseif, for, foreach, if, switch, while), to help distinguish them from functions and increase readability.
+
+**INCORRECT:**
+:::PHP
+# $arr[ $foo ] = 'foo';
+
+**CORRECT:**
+:::PHP
+# $arr[$foo] = 'foo'; // no spaces around array keys
+
+**INCORRECT:**
+:::PHP
+# function foo ( $bar )
+# {
+# 
+# }
+
+**CORRECT:**
+:::PHP
+# function foo($bar) // no spaces around parenthesis in function declarations
+# {
+# 
+# }
+
+**INCORRECT:**
+:::PHP
+# foreach( $query->result() as $row )
+ 
+**CORRECT:**
+:::PHP
+# foreach ($query->result() as $row) // single space following PHP control structures, but not in interior parenthesis
+
+## One Class Per File
+
+Use separate files for each class, unless the classes are closely related. For example, the Database class and the DBCache class might exist in the same file.
+
+## Private Methods and Variables
+
+Methods and variables that are only accessed internally by your class, such as utility and helper functions that your public methods use for code abstraction, should be prefixed with an underscore.
+
+## Short Open Tags
+
+Always use full PHP opening tags, in case a server does not have short_open_tag enabled.
+
+## Strings
+
+Always use single quoted strings unless you need variables parsed, and in cases where you do need variables parsed, use braces to prevent greedy token parsing. You may also use double-quoted strings if the string contains single quotes, so you do not have to use escape characters.
+
+**INCORRECT:**
+:::PHP
+# "My String"                                // no variable parsing, so no use for double quotes
+# "My string $foo"                           // needs braces
+# 'SELECT foo FROM bar WHERE baz = \'bag\''  // ugly
+
+**CORRECT:**
+:::PHP
+# 'My String'
+# "My string {$foo}"
+# "SELECT foo FROM bar WHERE baz = 'bag'"
+
+## SQL Queries
+
+MySQL keywords are always capitalized: SELECT, INSERT, UPDATE, WHERE, AS, JOIN, ON, IN, etc.
+
+Break up long queries into multiple lines for legibility, preferably breaking for each clause.
+

Coding Guidelines modified by Sean Callaway

Sean Callaway — Fri, 28 Feb 2014 05:40:33 -0000

--- v1
+++ v2
@@ -1,15 +1,48 @@
 PEBDesk PHP Coding Guidelines
+
 ===
+
+

 This document is still under construction and is, by no means, complete.

+
+
 [TOC]
+
+

 # Files and Folders

+
+
 ## Folder Structure and Organization
+
+
+
+From the root of the project, the following folders will exists:
+
+* "includes" - for PHP include files
+* "script" - for JavaScript files
+* "sql" - for SQL files
+* "style" - for CSS
+* "templates" - for PHP template files

 ## File Naming

+
+
+
+
+### File Extensions
+
+All PHP pages will have the ".php" extension. All PHP include files will have the ".inc.php" extension. All PHP template files will have the ".tpl.php" extension.
+
+All SQL files will have the ".sql" extension.
+
+All CSS files will have the ."css" extension.
+
+All JavaScript files will have the ".js" extension.
+
 # PHP Coding Style