medardm · November 2, 2018 02:18 · Jan 30, 2014 · Jan 29, 2014 · Jan 29, 2014 · Jan 29, 2014
diff --git a/php-style-guide.md b/php-style-guide.md
@@ -3489,5 +3489,5 @@ $firstname = call_user_func(array($User, 'get_firstname'));
 
 &#9650; [Table of Contents](#table-of-contents)
 
-Inspired in part by code standards from:<br />
+Inspired in part by style guides from:<br />
 [CodeIgniter](http://ellislab.com/codeigniter/user-guide/general/styleguide.html), [Drupal](https://drupal.org/coding-standards), [Horde](http://www.horde.org/apps/horde/docs/CODING_STANDARDS), [Pear](http://pear.php.net/manual/en/standards.php), [PSR-1](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md), [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md), [Symfony](http://symfony.com/doc/current/contributing/code/standards.html), and [WordPress](http://make.wordpress.org/core/handbook/coding-standards/php/).
diff --git a/php-style-guide.md b/php-style-guide.md
@@ -573,7 +573,7 @@ This section describes how comments should be formatted and used.
 
 ### 1. Single-line Comments
 
-Single-line comments SHOULD use two forward slashes.
+Single-line comments MUST use two forward slashes.
 
 #### &#10006; Incorrect
 

diff --git a/html-style-guide.md b/html-style-guide.md
@@ -1,42 +0,0 @@
-# HTML Style Guide
-
-All rules and guidelines in this document apply to HTML files.
-
-> The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
-
-**Icon Legend**:
-
-`·` Space, `⇥` Tab, `↵` Enter/Return
-
-<!-- ---------------------------------------------------------------------- -->
-
-## Table of Contents
-
-1. [**Files**](#1-files)
-	1. [File Format](#file-format)
-	2. [Filename](#filename)
-
-<!-- ---------------------------------------------------------------------- -->
-
-## 1. Files
-
-This section describes the format and naming convention of PHP files.
-
-#### File Format
-
-1. **Character encoding** MUST be set to UTF-8 without BOM
-	* Sublime.app &rarr; `File` &#8250; `Save with Encoding` &#8250; `UTF-8`
-2. **Line endings** MUST be set to Unix (LF)
-	* Sublime.app &rarr; `View` &#8250; `Line Endings` &#8250; `Unix`
-
-#### Filename
-
-1. **Letters** MUST be all lowercase
-	* e.g. `sidebar.html`, `index.php`
-2. **Words** MUST be separated with a hyphen
-	* e.g. `social-media.html`, `contact-widget.php`
-
-&#9650; [Table of Contents](#table-of-contents)
-
-<!-- ---------------------------------------------------------------------- -->
-

diff --git a/html-style-guide.md b/html-style-guide.md
@@ -8,4 +8,35 @@ All rules and guidelines in this document apply to HTML files.
 
 `·` Space, `⇥` Tab, `↵` Enter/Return
 
-<!-- ---------------------------------------------------------------------- -->
+<!-- ---------------------------------------------------------------------- -->
+
+## Table of Contents
+
+1. [**Files**](#1-files)
+	1. [File Format](#file-format)
+	2. [Filename](#filename)
+
+<!-- ---------------------------------------------------------------------- -->
+
+## 1. Files
+
+This section describes the format and naming convention of PHP files.
+
+#### File Format
+
+1. **Character encoding** MUST be set to UTF-8 without BOM
+	* Sublime.app &rarr; `File` &#8250; `Save with Encoding` &#8250; `UTF-8`
+2. **Line endings** MUST be set to Unix (LF)
+	* Sublime.app &rarr; `View` &#8250; `Line Endings` &#8250; `Unix`
+
+#### Filename
+
+1. **Letters** MUST be all lowercase
+	* e.g. `sidebar.html`, `index.php`
+2. **Words** MUST be separated with a hyphen
+	* e.g. `social-media.html`, `contact-widget.php`
+
+&#9650; [Table of Contents](#table-of-contents)
+
+<!-- ---------------------------------------------------------------------- -->
+
diff --git a/html-style-guide.md b/html-style-guide.md
@@ -0,0 +1,11 @@
+# HTML Style Guide
+
+All rules and guidelines in this document apply to HTML files.
+
+> The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
+
+**Icon Legend**:
+
+`·` Space, `⇥` Tab, `↵` Enter/Return
+
+<!-- ---------------------------------------------------------------------- -->
diff --git a/php-code-standards-style-guide.md → php-style-guide.md b/php-code-standards-style-guide.md → php-style-guide.md
@@ -1,4 +1,4 @@
-# PHP Code Standards & Style Guide
+# PHP Style Guide
 
 All rules and guidelines in this document apply to PHP files unless otherwise noted. References to PHP/HTML files can be interpreted as files that primarily contain HTML, but use PHP for templating purposes.
 

diff --git a/php-style-guide-code-standards.md → php-code-standards-style-guide.md b/php-style-guide-code-standards.md → php-code-standards-style-guide.md
@@ -1,4 +1,4 @@
-# PHP Code Standards
+# PHP Code Standards & Style Guide
 
 All rules and guidelines in this document apply to PHP files unless otherwise noted. References to PHP/HTML files can be interpreted as files that primarily contain HTML, but use PHP for templating purposes.
 

diff --git a/php-style-guide-code-standards.md b/php-style-guide-code-standards.md
@@ -754,7 +754,7 @@ Blocks of code SHOULD be explained or summarized.
 <pre lang=php>
 &lt;?php
 
-foreach ($users as $User) {
+foreach ($users as $user) {
 	if ($expr1) {
 		// ...
 	} else {
@@ -786,7 +786,7 @@ foreach ($users as $User) {
  * If no photo exists on website, check intranet.
  * If neither location has photo, send user email to upload one.
  */
-foreach ($users as $User) {
+foreach ($users as $user) {
 	if ($expr1) {
 		// ...
 	} else {
@@ -860,7 +860,7 @@ include_once 'some-file.php';
 
 // ...
 
-foreach($users as $User) {
+foreach($users as $user) {
 	// ...
 }
 
@@ -880,7 +880,7 @@ include_once 'some-file.php';
 // ...
 
 // $users from some-file.php
-foreach($users as $User) {
+foreach($users as $user) {
 	// ...
 }
 
@@ -2593,7 +2593,7 @@ This section describes class files, names, definitions, properties, methods and
 	* MUST start with capital letter
 	* MUST be camelcase
 	* MUST include parenthesis
-	* e.g. `$User = new User();`, `$OfficeProgram = new OfficeProgram();`
+	* e.g. `$user = new User();`, `$OfficeProgram = new OfficeProgram();`
 
 &#9650; [Table of Contents](#table-of-contents)
 

diff --git a/php-style-guide-code-standards.md b/php-style-guide-code-standards.md
@@ -1,4 +1,4 @@
-# PHP Style Guide & Code Standards
+# PHP Code Standards
 
 All rules and guidelines in this document apply to PHP files unless otherwise noted. References to PHP/HTML files can be interpreted as files that primarily contain HTML, but use PHP for templating purposes.
 
@@ -750,7 +750,7 @@ print_welcome_message();
 Blocks of code SHOULD be explained or summarized.
 
 #### ~ Acceptable
-5. class
+
 <pre lang=php>
 &lt;?php
 

diff --git a/php-code-standards.md → php-style-guide-code-standards.md b/php-code-standards.md → php-style-guide-code-standards.md
@@ -1,4 +1,4 @@
-# PHP Code Standards
+# PHP Style Guide & Code Standards
 
 All rules and guidelines in this document apply to PHP files unless otherwise noted. References to PHP/HTML files can be interpreted as files that primarily contain HTML, but use PHP for templating purposes.
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -690,7 +690,7 @@ Divider comments SHOULD use the block format with 75 asterisks in between.
 
 </pre>
 
-&#8627; Incorrect because it uses 10 `*` instead of 75.
+&#8627; Incorrect because it uses 10 instead of 75 `*`.
 
 #### &#10004; Correct
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -36,10 +36,12 @@ Most sections are broken up into two parts:
 6. [**Comments**](#6-comments)
 	1. [Single-line Comments](#1-single-line-comments)
 	2. [Multi-line Comments](#2-multi-line-comments)
-	3. [Comments](#3-comments)
-	4. [Blocks of Code](#4-blocks-of-code)
-	5. [Ambiguous Numbers](#5-ambiguous-numbers)
-	6. [External Variables](#6-external-variables)
+	3. [Header Comments](#3-header-comments)
+	4. [Divider Comments](#4-divider-comments)
+	5. [Comments](#5-comments)
+	6. [Blocks of Code](#6-blocks-of-code)
+	7. [Ambiguous Numbers](#7-ambiguous-numbers)
+	8. [External Variables](#8-external-variables)
 7. [**Includes**](#7-includes)
 	1. [Include/Require Once](#1-includerequire-once)
 	2. [Parenthesis](#2-parenthesis)
@@ -548,17 +550,21 @@ namespace MyCompany\View {
 
 This section describes how comments should be formatted and used.
 
-1. **[Single-line comments](#1-single-line-comments)** MUST use a forward slashes
+1. **[Single-line comments](#1-single-line-comments)** MUST use two forward slashes
 	* e.g. `// My comment`
 2. **[Multi-line comments](#2-multi-line-comments)** MUST use the block format
 	* i.e. `/**` `↵` `* My comment` `↵` `*/`
-3. **[Comments](#3-comments)** MUST be on their own line
+3. **[Header comments](#3-header-comments)** SHOULD use the block format
+	* i.e. `/**` `↵` `* Name of code section` `↵` `*/`
+4. **[Divider comments](#4-divider-comments)** SHOULD use the block format with asterisks in between
+	* i.e. `/**` `75 asterisks` `*/`
+5. **[Comments](#5-comments)** MUST be on their own line
 	* i.e. `↵` `// My comment`
-4. **[Blocks of code](#4-blocks-of-code)** SHOULD be explained or summarized
+6. **[Blocks of code](#6-blocks-of-code)** SHOULD be explained or summarized
 	* e.g. `// Compare user accounts from export against expired accounts in system`
-5. **[Ambiguous numbers](#5-ambiguous-numbers)** MUST be clarified
+7. **[Ambiguous numbers](#7-ambiguous-numbers)** MUST be clarified
 	* e.g. `// 1,000 processable records per hour API limit`
-6. **[External variables](#6-external-variables)** MUST be clarified
+8. **[External variables](#8-external-variables)** MUST be clarified
 	* e.g. `// Database object included in file.php`
 
 &#9650; [Table of Contents](#table-of-contents)
@@ -567,7 +573,7 @@ This section describes how comments should be formatted and used.
 
 ### 1. Single-line Comments
 
-Single-line comments MUST use forward slashes.
+Single-line comments SHOULD use two forward slashes.
 
 #### &#10006; Incorrect
 
@@ -635,7 +641,78 @@ Multi-line comments MUST use the block format.
 
 <!-- ------------------------------ -->
 
-### 3. Comments
+### 3. Header Comments
+
+Header comments SHOULD use the block format.
+
+<pre lang=php>
+&lt;?php
+
+/**
+ * Global application settings
+ */
+
+define('SETTING_ONE', '');
+define('SETTING_TWO', '');
+define('SETTING_THREE', '');
+
+// EOF
+
+</pre>
+
+&#9650; [Comments](#6-comments)
+
+<!-- ------------------------------ -->
+
+### 4. Divider Comments
+
+Divider comments SHOULD use the block format with 75 asterisks in between.
+
+#### &#10006; Incorrect
+
+<pre lang=php>
+&lt;?php
+
+/**#######################################################################*/
+
+// EOF
+
+</pre>
+
+&#8627; Incorrect because it uses `#` instead of `*`.
+
+<pre lang=php>
+&lt;?php
+
+/*************/
+
+// EOF
+
+</pre>
+
+&#8627; Incorrect because it uses 10 `*` instead of 75.
+
+#### &#10004; Correct
+
+<pre lang=php>
+&lt;?php
+
+/**
+ * Beginning + Middle + End
+ * 3 spaces + 75 spaces + 2 spaces = 80 character line limit
+ */
+
+/******************************************************************************/
+
+// EOF
+
+</pre>
+
+&#9650; [Comments](#6-comments)
+
+<!-- ------------------------------ -->
+
+### 5. Comments
 
 Comment MUST be on their own line.
 
@@ -668,7 +745,7 @@ print_welcome_message();
 
 <!-- ------------------------------ -->
 
-### 4. Blocks of Code
+### 6. Blocks of Code
 
 Blocks of code SHOULD be explained or summarized.
 
@@ -733,7 +810,7 @@ foreach ($users as $User) {
 
 <!-- ------------------------------ -->
 
-### 5. Ambiguous Numbers
+### 7. Ambiguous Numbers
 
 Ambiguous numbers MUST be clarified.
 
@@ -770,7 +847,7 @@ while ($expr && $x &lt; 1000) {
 
 <!-- ------------------------------ -->
 
-### 6. External Variables
+### 8. External Variables
 
 External variables MUST be clarified.
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -1706,7 +1706,7 @@ This section describes the format for function names, calls, arguments and decla
 	* MUST use descriptive defaults
 	* MUST use type hinting
 	* e.g. `func($arg1, $arg2 = 'asc', $arg3 = 100);`
-5. [**Function declaration**](#5-function-declaration) MUST be documented using [phpDocumentor](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) tag style and SHOULD include
+5. [**Function declaration**](#5-function-declaration) MUST be documented using [phpDocumentor](http://phpdoc.org/docs/latest/index.html) tag style and SHOULD include
 	* Short description
 	* Optional long description, if needed
 	* @access: `private` or `protected` (assumed `public`)
@@ -1987,7 +1987,7 @@ function add_users_to_office(array $users, Office $office) {
 
 ### 5. Function Declaration
 
-Function declaration MUST be documented using [phpDocumentor](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) tag style and SHOULD include:
+Function declaration MUST be documented using [phpDocumentor](http://phpdoc.org/docs/latest/index.html) tag style and SHOULD include:
 
 * Short description
 * Optional long description, if needed
@@ -2498,7 +2498,7 @@ This section describes class files, names, definitions, properties, methods and
 	* e.g. `namespace MyCompany\Model;`, `namespace MyCompany\View;`, `namespace MyCompany\Controller;`
 3. [**Class name**](#3-class-name) MUST start with a capital letter and MUST be camelcase
 	* e.g. `MyCompany`
-4. [**Class documentation**](#4-class-documentation) MUST be present and MUST use [phpDocumentor](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) tag style
+4. [**Class documentation**](#4-class-documentation) MUST be present and MUST use [phpDocumentor](http://phpdoc.org/docs/latest/index.html) tag style
 	* i.e. `@author`, `@global`, `@package`
 5. [**Class definition**](#5-class-definition) MUST place curly braces on their own line
 	* i.e. `class User` `↵` `{` `↵` `...` `↵` `}`
@@ -2723,7 +2723,7 @@ class OfficeProgram
 
 ### 4. Class Documentation
 
-Class documentation MUST be present and MUST use [phpDocumentor](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) tag style.
+Class documentation MUST be present and MUST use [phpDocumentor](http://phpdoc.org/docs/latest/index.html) tag style.
 
 #### &#10006; Incorrect
 
@@ -2760,7 +2760,7 @@ class User
 
 </pre>
 
-&#8627; Incorrect because `User` is missing phpDocumentor tags.
+&#8627; Incorrect because `User` is missing [phpDocumentor](http://phpdoc.org/docs/latest/index.html) tags.
 
 #### &#10004; Correct
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -2028,10 +2028,10 @@ function my_function($id, $type, $width, $height) {
  * @access private
  * @author Firstname Lastname
  * @global object $post
- * @param int [$id] Author ID
- * @param string [$type] Type of photo
- * @param int [$width] Photo width in px
- * @param int [$height] Photo height in px
+ * @param int $id Author ID
+ * @param string $type Type of photo
+ * @param int $width Photo width in px
+ * @param int $height Photo height in px
  * @return object Photo
  */
 function my_function($id, $type, $width, $height) {

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -2164,7 +2164,7 @@ This section defines the layout and usage of control structures. Note that this
 * **Closing brace** MUST start on the next line
 	* i.e. `...` `↵` `}`
 * **Nesting** MUST NOT exceed three levels
-	* e.g. no `if ($expr1) { if ($expr2) { if ($expr3) { if ($expr4) { ` `...` `}}}`
+	* e.g. no `if ($expr1) { if ($expr2) { if ($expr3) { if ($expr4) { ` `...` `}}}}`
 
 In addition to the rules above, some control structures have additional requirements:
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -2164,7 +2164,7 @@ This section defines the layout and usage of control structures. Note that this
 * **Closing brace** MUST start on the next line
 	* i.e. `...` `↵` `}`
 * **Nesting** MUST NOT exceed three levels
-	* i.e. no `if ($expr1) { if ($expr2) { if ($expr3) {` `...` `}}}`
+	* e.g. no `if ($expr1) { if ($expr2) { if ($expr3) { if ($expr4) { ` `...` `}}}`
 
 In addition to the rules above, some control structures have additional requirements:
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -2163,6 +2163,8 @@ This section defines the layout and usage of control structures. Note that this
 	* e.g. `if ($expr) {` `↵` `⇥` `...` `↵` `}`
 * **Closing brace** MUST start on the next line
 	* i.e. `...` `↵` `}`
+* **Nesting** MUST NOT exceed three levels
+	* i.e. no `if ($expr1) { if ($expr2) { if ($expr3) {` `...` `}}}`
 
 In addition to the rules above, some control structures have additional requirements:
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -1933,28 +1933,28 @@ function get_objects($limit, $order, $type) {
 <pre lang=php>
 &lt;?php
 
-function add_users_to_office($users, $office) {
+function get_objects($type, $order = true, $limit = 100) {
 	// ...
 }
 
 // EOF
 
 </pre>
 
-&#8627; Incorrect because `$users` and `$office` are missing their data type.
+&#8627; Incorrect because `true` is not a descriptive default for `$order`.
 
 <pre lang=php>
 &lt;?php
 
-function get_objects($type, $order = true, $limit = 100) {
+function add_users_to_office($users, $office) {
 	// ...
 }
 
 // EOF
 
 </pre>
 
-&#8627; Incorrect because `true` is not a descriptive default for `$order`.
+&#8627; Incorrect because `$users` and `$office` are missing their data type.
 
 #### &#10004; Correct
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -1704,6 +1704,7 @@ This section describes the format for function names, calls, arguments and decla
 	* MUST be ordered from required to optional first
 	* MUST be ordered from high to low importance second
 	* MUST use descriptive defaults
+	* MUST use type hinting
 	* e.g. `func($arg1, $arg2 = 'asc', $arg3 = 100);`
 5. [**Function declaration**](#5-function-declaration) MUST be documented using [phpDocumentor](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) tag style and SHOULD include
 	* Short description
@@ -1716,7 +1717,7 @@ This section describes the format for function names, calls, arguments and decla
 6. [**Function return**](#6-function-return)
 	* MUST occur as early as possible 
 	* MUST be initialized prior at top
-	* SHOULD be preceded by blank line, except inside control statement
+	* MUST be preceded by blank line, except inside control statement
 	* i.e. `if (!$expr) { return false; }`
 
 &#9650; [Table of Contents](#table-of-contents)
@@ -1848,6 +1849,7 @@ Function arguments:
 * MUST be ordered from required to optional first
 * MUST be ordered from high to low importance second
 * MUST use descriptive defaults
+* MUST use type hinting
 
 #### &#10006; Incorrect
 
@@ -1931,6 +1933,19 @@ function get_objects($limit, $order, $type) {
 <pre lang=php>
 &lt;?php
 
+function add_users_to_office($users, $office) {
+	// ...
+}
+
+// EOF
+
+</pre>
+
+&#8627; Incorrect because `$users` and `$office` are missing their data type.
+
+<pre lang=php>
+&lt;?php
+
 function get_objects($type, $order = true, $limit = 100) {
 	// ...
 }
@@ -1958,6 +1973,10 @@ function get_objects($type, $order = 'asc', $limit = 100) {
 	// ...
 }
 
+function add_users_to_office(array $users, Office $office) {
+	// ...
+}
+
 // EOF
 
 </pre>

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -3290,7 +3290,6 @@ $pdo = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
 
 function get_user($id) {
 	global $pdo;
-
 	// ...
 }
 
@@ -3311,7 +3310,6 @@ function get_database_object() {
 
 function get_user($id) {
 	$pdo = get_database_object();
-
 	// ...
 }
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -85,8 +85,9 @@ Most sections are broken up into two parts:
 12. [**Best Practices**](#12-best-practices)
 	1. [Variable Initialization](#1-variable-initialization)
 	2. [Initialization/Declaration Order](#2-initializationdeclaration-order)
-	3. [Explicit Expressions](#3-explicit-expressions)
-	4. [E_STRICT Reporting](#4-e_strict-reporting)
+	3. [Globals](#3-globals)
+	4. [Explicit Expressions](#4-explicit-expressions)
+	5. [E_STRICT Reporting](#5-e_strict-reporting)
 
 <!-- ---------------------------------------------------------------------- -->
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -3027,11 +3027,11 @@ $office_program = new OfficeProgram();
 	* MUST lead with `public`, follow with `protected`, conclude with `private` methods in classes
 	* SHOULD be alphabetical within their type
 	* i.e. `global $var1;`, `define('VAR2', '');`, `$var3 = 0;`
-3. [**Globals**](#3-globals) SHOULD NOT be used
+3. [**Globals**](#4-globals) SHOULD NOT be used
 	* i.e. no `global $var;`
-4. [**Explicit expressions**](#4-explicit-expressions) SHOULD be used
+4. [**Explicit expressions**](#5-explicit-expressions) SHOULD be used
 	* e.g. `if ($expr === false)`, `while ($expr !== true)`
-5. [**E_STRICT reporting**](#5-e_strict-reporting) MUST NOT trigger errors
+5. [**E_STRICT reporting**](#6-e_strict-reporting) MUST NOT trigger errors
 	* i.e. do not use deprecated functions, etc.
 
 &#9650; [Table of Contents](#table-of-contents)
@@ -3276,7 +3276,53 @@ function get_movies() {
 
 <!-- ------------------------------ -->
 
-### 3. Explicit Expressions
+### 3. Globals
+
+Globals SHOULD NOT be used.
+
+#### ~ Acceptable
+
+<pre lang=php>
+&lt;?php
+
+$pdo = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
+
+function get_user($id) {
+	global $pdo;
+
+	// ...
+}
+
+// EOF
+
+</pre>
+
+&#8627; Acceptable, but `global` variables should be avoided.
+
+#### &#10004; Preferred
+
+<pre lang=php>
+&lt;?php
+
+function get_database_object() {
+	return new PDO('mysql:host=localhost;dbname=test', $user, $pass);
+}
+
+function get_user($id) {
+	$pdo = get_database_object();
+
+	// ...
+}
+
+// EOF
+
+</pre>
+
+&#9650; [Best Practices](#12-best-practices)
+
+<!-- ------------------------------ -->
+
+### 4. Explicit Expressions
 
 Explicit expressions SHOULD be used.
 
@@ -3312,7 +3358,7 @@ if ($expr === true) {
 
 <!-- ------------------------------ -->
 
-### 4. E_STRICT Reporting
+### 5. E_STRICT Reporting
 
 E_STRICT reporting MUST NOT trigger errors.
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -2738,7 +2738,7 @@ class User
 
 </pre>
 
-&#8627; Incorrect because `User` is not documented using phpDocumentaer tag style.
+&#8627; Incorrect because `User` is missing phpDocumentor tags.
 
 #### &#10004; Correct
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -2727,7 +2727,7 @@ class User
 namespace MyCompany\View;
 
 /**
- * Prepares data for user profile
+ * User View
  */
 class User
 {

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -77,10 +77,11 @@ Most sections are broken up into two parts:
 	1. [Class File](#1-class-file)
 	2. [Class Namespace](#2-class-namespace)
 	3. [Class Name](#3-class-name)
-	4. [Class Definition](#4-class-definition)
-	5. [Class Properties](#5-class-properties)
-	6. [Class Methods](#6-class-methods)
-	7. [Class Instance](#7-class-instance)
+	4. [Class Documentation](#4-class-documentation)
+	5. [Class Definition](#5-class-definition)
+	6. [Class Properties](#6-class-properties)
+	7. [Class Methods](#7-class-methods)
+	8. [Class Instance](#8-class-instance)
 12. [**Best Practices**](#12-best-practices)
 	1. [Variable Initialization](#1-variable-initialization)
 	2. [Initialization/Declaration Order](#2-initializationdeclaration-order)
@@ -2475,19 +2476,21 @@ This section describes class files, names, definitions, properties, methods and
 	* e.g. `namespace MyCompany\Model;`, `namespace MyCompany\View;`, `namespace MyCompany\Controller;`
 3. [**Class name**](#3-class-name) MUST start with a capital letter and MUST be camelcase
 	* e.g. `MyCompany`
-4. [**Class definition**](#4-class-definition) MUST place curly braces on their own line
+4. [**Class documentation**](#4-class-documentation) MUST be present and MUST use [phpDocumentor](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) tag style
+	* i.e. `@author`, `@global`, `@package`
+5. [**Class definition**](#5-class-definition) MUST place curly braces on their own line
 	* i.e. `class User` `↵` `{` `↵` `...` `↵` `}`
-5. [**Class properties**](#5-class-properties)
+6. [**Class properties**](#6-class-properties)
 	* MUST follow [variable standards](#7-variables)
 	* MUST specify visibility
 	* MUST NOT be prefixed with an underscore if private or protected
 	* e.g. `$var1;`, `private $var2;`, `protected $var3;`
-6. [**Class methods**](#6-class-methods)
+7. [**Class methods**](#7-class-methods)
 	* MUST follow [function standards](#9-functions)
 	* MUST specify visibility
 	* MUST NOT be prefixed with an underscore if private or protected
 	* e.g. `func1()`, `private func2()`, `protected func3()`
-7. [**Class instance**](#7-class-instance)
+8. [**Class instance**](#8-class-instance)
 	* MUST start with capital letter
 	* MUST be camelcase
 	* MUST include parenthesis
@@ -2696,7 +2699,75 @@ class OfficeProgram
 
 <!-- ------------------------------ -->
 
-### 4. Class Definition
+### 4. Class Documentation
+
+Class documentation MUST be present and MUST use [phpDocumentor](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) tag style.
+
+#### &#10006; Incorrect
+
+<pre lang=php>
+&lt;?php
+
+namespace MyCompany\Model;
+
+class User
+{
+	// ...
+}
+
+// EOF
+
+</pre>
+
+&#8627; Incorrect because `User` is missing documentation.
+
+<pre lang=php>
+&lt;?php
+
+namespace MyCompany\View;
+
+/**
+ * Prepares data for user profile
+ */
+class User
+{
+	// ...
+}
+
+// EOF
+
+</pre>
+
+&#8627; Incorrect because `User` is not documented using phpDocumentaer tag style.
+
+#### &#10004; Correct
+
+<pre lang=php>
+&lt;?php
+
+namespace MyCompany\View;
+
+/**
+ * User View
+ *
+ * @author Firstname Lastname
+ * @global object $post
+ * @package MyCompany\API
+ */
+class User
+{
+	// ...
+}
+
+// EOF
+
+</pre>
+
+&#9650; [Classes](#11-classes)
+
+<!-- ------------------------------ -->
+
+### 5. Class Definition
 
 Class definition MUST place curly braces on their own line.
 
@@ -2737,7 +2808,7 @@ class User
 
 <!-- ------------------------------ -->
 
-### 5. Class Properties
+### 6. Class Properties
 
 Class properties:
 
@@ -2810,7 +2881,7 @@ class User
 
 <!-- ------------------------------ -->
 
-### 6. Class Methods
+### 7. Class Methods
 
 Class methods:
 
@@ -2911,7 +2982,7 @@ class User
 
 <!-- ------------------------------ -->
 
-### 7. Class Instance
+### 8. Class Instance
 
 Class instance:
 
@@ -3050,6 +3121,8 @@ global $app_config;
 <pre lang=php>
 &lt;?php
 
+namespace MyCompany\Model;
+
 class Office
 {
 	public function get_name() {
@@ -3068,6 +3141,8 @@ class Office
 <pre lang=php>
 &lt;?php
 
+namespace MyCompany\Model;
+
 class Office
 {
 	private $id;
@@ -3155,6 +3230,8 @@ $lastname = '';
 <pre lang=php>
 &lt;?php
 
+namespace MyCompany\Model;
+
 class Office
 {
 	private $id;

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -2953,7 +2953,7 @@ $office_program = new OfficeProgram();
 2. [**Initialization/declaration order**](#2-initializationdeclaration-order)
 	* MUST lead with globals, follow with constants, conclude with local variables
 	* MUST lead with properties and follow with methods in classes
-	* MUST lead with public, follow with protected, conclude with private methods in classes
+	* MUST lead with `public`, follow with `protected`, conclude with `private` methods in classes
 	* SHOULD be alphabetical within their type
 	* i.e. `global $var1;`, `define('VAR2', '');`, `$var3 = 0;`
 3. [**Globals**](#3-globals) SHOULD NOT be used
@@ -3027,7 +3027,7 @@ Initialization/declaration order:
 
 * MUST lead with globals, follow with constants, conclude with local variables
 * MUST lead with properties and follow with methods in classes
-* MUST lead with public, follow with protected, conclude with private methods in classes
+* MUST lead with `public`, follow with `protected`, conclude with `private` methods in classes
 * SHOULD be alphabetical within their type
 
 #### &#10006; Incorrect

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -83,7 +83,7 @@ Most sections are broken up into two parts:
 	7. [Class Instance](#7-class-instance)
 12. [**Best Practices**](#12-best-practices)
 	1. [Variable Initialization](#1-variable-initialization)
-	2. [Declaration Order](#2-declaration-order)
+	2. [Initialization/Declaration Order](#2-initializationdeclaration-order)
 	3. [Explicit Expressions](#3-explicit-expressions)
 	4. [E_STRICT Reporting](#4-e_strict-reporting)
 

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -2950,7 +2950,7 @@ $office_program = new OfficeProgram();
 
 1. [**Variable initialization**](#1-variable-initialization) SHOULD occur prior to use and SHOULD occur early
 	* e.g. `$var1 = '';`, `$var2 = 0;`
-2. [**Declaration order**](#2-declaration-order)
+2. [**Initialization/declaration order**](#2-initializationdeclaration-order)
 	* MUST lead with globals, follow with constants, conclude with local variables
 	* MUST lead with properties and follow with methods in classes
 	* MUST lead with public, follow with protected, conclude with private methods in classes
@@ -3021,9 +3021,9 @@ $movies = get_movies();
 
 <!-- ------------------------------ -->
 
-### 2. Declaration Order
+### 2. Initialization/Declaration Order
 
-Declaration order:
+Initialization/declaration order:
 
 * MUST lead with globals, follow with constants, conclude with local variables
 * MUST lead with properties and follow with methods in classes

diff --git a/php-code-standards.md b/php-code-standards.md
@@ -1714,7 +1714,7 @@ This section describes the format for function names, calls, arguments and decla
 6. [**Function return**](#6-function-return)
 	* MUST occur as early as possible 
 	* MUST be initialized prior at top
-	* SHOULD be preceded by blank line
+	* SHOULD be preceded by blank line, except inside control statement
 	* i.e. `if (!$expr) { return false; }`
 
 &#9650; [Table of Contents](#table-of-contents)
@@ -2032,7 +2032,7 @@ Function return:
 
 * MUST occur as early as possible 
 * MUST be initialized prior at top
-* MUST be preceded by blank line, unless inside control statement
+* MUST be preceded by blank line, except inside control statement
 
 #### &#10006; Incorrect