From 807ae30cb037b827319b924994952daf57db2a40 Mon Sep 17 00:00:00 2001
From: cash <cash.costello@gmail.com>
Date: Sun, 3 Jul 2011 08:58:58 -0400
Subject: separate out coding standards

---
 CODING.txt                                         | 222 ---------------------
 documentation/coding_standards/best_practices.txt  |  96 +++++++++
 .../coding_standards/css_coding_standards.txt      |  67 +++++++
 .../coding_standards/html_best_practices.txt       |   1 +
 .../coding_standards/javascript_best_practices.txt |   1 +
 .../javascript_coding_standards.txt                |   2 +
 .../coding_standards/php_best_practices.txt        |   1 +
 .../coding_standards/php_coding_standards.txt      |  55 +++++
 8 files changed, 223 insertions(+), 222 deletions(-)
 delete mode 100644 CODING.txt
 create mode 100644 documentation/coding_standards/best_practices.txt
 create mode 100644 documentation/coding_standards/css_coding_standards.txt
 create mode 100644 documentation/coding_standards/html_best_practices.txt
 create mode 100644 documentation/coding_standards/javascript_best_practices.txt
 create mode 100644 documentation/coding_standards/javascript_coding_standards.txt
 create mode 100644 documentation/coding_standards/php_best_practices.txt
 create mode 100644 documentation/coding_standards/php_coding_standards.txt

diff --git a/CODING.txt b/CODING.txt
deleted file mode 100644
index 355601720..000000000
--- a/CODING.txt
+++ /dev/null
@@ -1,222 +0,0 @@
-*** CODING STANDARDS ***
-
-These are the coding standards for Elgg.  All core development, bundled 
-plugins, and tickets attached to Trac are expected to be in this format.
-
-** PHP **
-
-* 	Unix line endings.
-
-* 	Hard tabs, 4 character tab spacing.
-
-* 	No PHP shortcut tags ( <? or <?= or <% ).
-
-* 	PHPDoc comments on functions and classes (all methods; declared properties
-	when appropriate).
-
-* 	Mandatory wrapped {}s around any code blocks. 
-		Bad:
-		if (true) 
-			foreach($arr as $elem) 
-				echo $elem;
-	
-		Good:
-		if (true) {
-			foreach($arr as $elem) {
-				echo $elem;
-			}
-		}
-
-* 	Name standalone functions using underscore_character().
-
-* 	Name classes using CamelCase() and methods using lowerCamelCase().
-
-* 	Name globals and constants in ALL_CAPS (TRUE, NULL, ACCESS_FRIENDS, $CONFIG).
-
-* 	Use underscores / camel case to separate standard English words in
-	functions, classes, and methods. (get_default_site(), ElggUser->isLoggedIn()).
-
-* 	Space functions like_this($required, $optional = TRUE).
-
-* 	Space keywords and constructs like this: if (FALSE) { ... }.
-
-* 	Correctly use spaces, quotes, and {}s in strings: 
-		Bad (hard to read, misuse of quotes and {}s): 
-		echo 'Hello, '.$name."!  How is your {$time_of_day}?";
-		
-		Good:
-		echo "Hello, $name!  How is your $time_of_day?"; 
-
-* 	Line lengths should be reasonable.  If you are writing lines over 100 
-	characters on a line, please revise the code.
-
-* 	Use // or /* */ when commenting.
-
-* 	No closing PHP tag (?>) at EOF unless after a heredoc. (Avoids problems with 
-	trailing whitespace. Required after heredoc by PHP.)
-
-** CSS **
-
-* 	Use shorthand where possible:
-		Bad:
-		background-color: #333333;
-		background-image:  url(...);
-		background-repeat:  repeat-x;
-		background-position:  left 10px;
-		padding: 2px 9px 2px 9px;
-		
-		Good:
-		background: #333 url(...) repeat-x left 10px;
-		padding: 2px 9px;
-
-* 	Use hyphens as separators in classes/ids, not underscores:
-		Bad:
-		.example_class
-		
-		Good:
-		.example-class
-	
-* 	One property per line
-		Bad:
-		color: white;font-size: smaller;
-		
-		Good:
-		color: white;
-		font-size: smaller;
-	
-* 	Property declarations should be spaced like so: `property: value;`
-		Bad:
-		color:value;
-		color :value;
-		color : value;
-		
-		Good:
-		color: value;
-
-* 	Group vendor-prefixes for the same property together:
-* 	Longest vendor-prefixed version first:
-* 	Always include non-vendor-prefixed version:
-* 	Put an extra newline between vendor-prefixed groups and other properties:
-		Bad:
-		-moz-border-radius: 5px;
-		border: 1px solid #999999;
-		-webkit-border-radius: 5px;
-		width: auto;
-		
-		Good:
-		border: 1px solid #999999;
-		
-		-webkit-border-radius: 5px;
-		-moz-border-radius: 5px;
-		border-radius: 5px;
-	
-		width: auto;
-
-* 	Group declarations of subproperties:
-		Bad:
-		background-color: white;
-		color: #0054A7;
-		background-position: 2px -257px;
-		
-		Good:
-		background-color: white;
-		background-position: 2px -257px;
-		color: #0054A7;
-
-
-*** CODING BEST PRACTICES ***
-
-The following best practices make code easier to read, easier to maintain,
-and easier to debug.  Consistent use of these guidelines means less guess
-work for developers, which means happier, more productive developers.
-
-* 	Adhere to "Don't Repeat Yourself" (DRY) principles of code design and 
-	organization. If you are copy-and-pasting code YOU ARE DOING SOMETHING WRONG.
-	If you find a block of code that you want to use multiple times, make a 
-	function.  If you find views that are identical except for a single value,
-	pull it out into a generic view that takes an option.
-
-* 	Whitespace is free.  Don't be afraid to use it to separate blocks of code. 
-	Use a single space to separate function params and string concatenation.
-
-* 	Use self-documenting variable names.  $group_guids is better than $array.
-
-* 	Functions returning an array should return an empty array instead of FALSE
-	on no results.
-
-* 	Functions not throwing an exception on error should return FALSE upon 
-	failure. 
-
-* 	Functions returning only boolean should be prefaced with is_ or has_ (eg,
-	elgg_is_logged_in(), elgg_has_access_to_entity()).
-
-* 	Ternary syntax is acceptable for single-line, non-embedded statements.
-
-* 	Use comments effectively.  Good comments describe the "why."  Good code
-	describes the "how."  Ex:
-		Not a very useful comment:
-	
-		// increment $i only when the entity is marked as active.
-		foreach($entities as $entity) {
-			if ($entity->active == TRUE) {
-				$i++;
-			}
-		}
-	
-		Useful comment:
-	
-		// find the next index for inserting a new active entity.
-		foreach($entities as $entity) {
-			if ($entity->active == TRUE) {
-				$i++;
-			}
-		}
-
-* 	Use commit messages effectively.  Be concise and meaningful. Ex:
-		Not meaningful:
-		Small fix to groups.
-	
-		Meaningful:
-		Fixes #1234: Added missing ) that caused a WSOD on group profile page
-		when logged out.
-
-* 	Commit effectively: Err on the side of atomic commits.  One revision with
-	many changes is scary.
-
-
-*** DEPRECATING APIs ***
-
-Occasionally, functions and classes must be deprecated in favor of newer
-replacements.  Since 3rd party plugin authors rely on a consistent API,
-backward compatibility must be maintained, but will not be maintained
-indefinitely as plugin authors are expected to properly update their
-plugins.  In order to maintain backward compatibility, deprecated APIs will
-follow these guidelines:
-
-* 	Incompatible API changes cannot occur between bugfix versions 
-	(1.6.0 - 1.6.1).
-
-* 	API changes between minor versions (1.6 - 1.7) must maintain backward
-	compatibility for at least 2 minor versions.  (1.7 and 1.8. See 
-	procedures, below.)
-
-* 	Bugfixes that change the API cannot be included in bugfix versions.
-
-* 	API changes between major versions (1.0 - 2.0) can occur without regard to
-	backward compatibility.
-
-The procedure for deprecating an API is as follows:
-
-* 	The first minor version (1.7) with a deprecated API must include a wrapper
-	function/class (or otherwise appropriate means) to maintain backward
-	compatibility, including any bugs in the original function/class.
-	This compatibility layer uses elgg_deprecated_notice('...', 1.7) to log
-	that the function is deprecated.
-
-* 	The second minor version (1.8) maintains the backward compatibility
-	layer, but elgg_deprecated_notice() will produce a visible warning.
-
-* 	The third minor version (1.9) removes the compatibility layer.  Any use of 
-	the deprecated API should be corrected before this.
-
-The general timeline for two minor releases is 8 to 12 months.
diff --git a/documentation/coding_standards/best_practices.txt b/documentation/coding_standards/best_practices.txt
new file mode 100644
index 000000000..68dcce38b
--- /dev/null
+++ b/documentation/coding_standards/best_practices.txt
@@ -0,0 +1,96 @@
+*** CODING BEST PRACTICES ***
+
+The following best practices make code easier to read, easier to maintain,
+and easier to debug.  Consistent use of these guidelines means less guess
+work for developers, which means happier, more productive developers.
+
+* 	Adhere to "Don't Repeat Yourself" (DRY) principles of code design and
+	organization. If you are copy-and-pasting code YOU ARE DOING SOMETHING WRONG.
+	If you find a block of code that you want to use multiple times, make a
+	function.  If you find views that are identical except for a single value,
+	pull it out into a generic view that takes an option.
+
+* 	Whitespace is free.  Don't be afraid to use it to separate blocks of code.
+	Use a single space to separate function params and string concatenation.
+
+* 	Use self-documenting variable names.  $group_guids is better than $array.
+
+* 	Functions returning an array should return an empty array instead of FALSE
+	on no results.
+
+* 	Functions not throwing an exception on error should return FALSE upon
+	failure.
+
+* 	Functions returning only boolean should be prefaced with is_ or has_ (eg,
+	elgg_is_logged_in(), elgg_has_access_to_entity()).
+
+* 	Ternary syntax is acceptable for single-line, non-embedded statements.
+
+* 	Use comments effectively.  Good comments describe the "why."  Good code
+	describes the "how."  Ex:
+		Not a very useful comment:
+
+		// increment $i only when the entity is marked as active.
+		foreach($entities as $entity) {
+			if ($entity->active == TRUE) {
+				$i++;
+			}
+		}
+
+		Useful comment:
+
+		// find the next index for inserting a new active entity.
+		foreach($entities as $entity) {
+			if ($entity->active == TRUE) {
+				$i++;
+			}
+		}
+
+* 	Use commit messages effectively.  Be concise and meaningful. Ex:
+		Not meaningful:
+		Small fix to groups.
+
+		Meaningful:
+		Fixes #1234: Added missing ) that caused a WSOD on group profile page
+		when logged out.
+
+* 	Commit effectively: Err on the side of atomic commits.  One revision with
+	many changes is scary.
+
+
+*** DEPRECATING APIs ***
+
+Occasionally, functions and classes must be deprecated in favor of newer
+replacements.  Since 3rd party plugin authors rely on a consistent API,
+backward compatibility must be maintained, but will not be maintained
+indefinitely as plugin authors are expected to properly update their
+plugins.  In order to maintain backward compatibility, deprecated APIs will
+follow these guidelines:
+
+* 	Incompatible API changes cannot occur between bugfix versions
+	(1.6.0 - 1.6.1).
+
+* 	API changes between minor versions (1.6 - 1.7) must maintain backward
+	compatibility for at least 2 minor versions.  (1.7 and 1.8. See
+	procedures, below.)
+
+* 	Bugfixes that change the API cannot be included in bugfix versions.
+
+* 	API changes between major versions (1.0 - 2.0) can occur without regard to
+	backward compatibility.
+
+The procedure for deprecating an API is as follows:
+
+* 	The first minor version (1.7) with a deprecated API must include a wrapper
+	function/class (or otherwise appropriate means) to maintain backward
+	compatibility, including any bugs in the original function/class.
+	This compatibility layer uses elgg_deprecated_notice('...', 1.7) to log
+	that the function is deprecated.
+
+* 	The second minor version (1.8) maintains the backward compatibility
+	layer, but elgg_deprecated_notice() will produce a visible warning.
+
+* 	The third minor version (1.9) removes the compatibility layer.  Any use of
+	the deprecated API should be corrected before this.
+
+The general timeline for two minor releases is 8 to 12 months.
diff --git a/documentation/coding_standards/css_coding_standards.txt b/documentation/coding_standards/css_coding_standards.txt
new file mode 100644
index 000000000..195ca345b
--- /dev/null
+++ b/documentation/coding_standards/css_coding_standards.txt
@@ -0,0 +1,67 @@
+*** CSS CODING STANDARDS ***
+
+* 	Use shorthand where possible:
+		Bad:
+		background-color: #333333;
+		background-image:  url(...);
+		background-repeat:  repeat-x;
+		background-position:  left 10px;
+		padding: 2px 9px 2px 9px;
+
+		Good:
+		background: #333 url(...) repeat-x left 10px;
+		padding: 2px 9px;
+
+* 	Use hyphens as separators in classes/ids, not underscores:
+		Bad:
+		.example_class
+
+		Good:
+		.example-class
+
+* 	One property per line
+		Bad:
+		color: white;font-size: smaller;
+
+		Good:
+		color: white;
+		font-size: smaller;
+
+* 	Property declarations should be spaced like so: `property: value;`
+		Bad:
+		color:value;
+		color :value;
+		color : value;
+
+		Good:
+		color: value;
+
+* 	Group vendor-prefixes for the same property together:
+* 	Longest vendor-prefixed version first:
+* 	Always include non-vendor-prefixed version:
+* 	Put an extra newline between vendor-prefixed groups and other properties:
+		Bad:
+		-moz-border-radius: 5px;
+		border: 1px solid #999999;
+		-webkit-border-radius: 5px;
+		width: auto;
+
+		Good:
+		border: 1px solid #999999;
+
+		-webkit-border-radius: 5px;
+		-moz-border-radius: 5px;
+		border-radius: 5px;
+
+		width: auto;
+
+* 	Group declarations of subproperties:
+		Bad:
+		background-color: white;
+		color: #0054A7;
+		background-position: 2px -257px;
+
+		Good:
+		background-color: white;
+		background-position: 2px -257px;
+		color: #0054A7;
diff --git a/documentation/coding_standards/html_best_practices.txt b/documentation/coding_standards/html_best_practices.txt
new file mode 100644
index 000000000..ac2338a77
--- /dev/null
+++ b/documentation/coding_standards/html_best_practices.txt
@@ -0,0 +1 @@
+*** HTML BEST PRACTICES ***
diff --git a/documentation/coding_standards/javascript_best_practices.txt b/documentation/coding_standards/javascript_best_practices.txt
new file mode 100644
index 000000000..9ec1d0a19
--- /dev/null
+++ b/documentation/coding_standards/javascript_best_practices.txt
@@ -0,0 +1 @@
+*** JAVASCRIPT BEST PRACTICES ***
diff --git a/documentation/coding_standards/javascript_coding_standards.txt b/documentation/coding_standards/javascript_coding_standards.txt
new file mode 100644
index 000000000..7d3b842ec
--- /dev/null
+++ b/documentation/coding_standards/javascript_coding_standards.txt
@@ -0,0 +1,2 @@
+*** JAVASCRIPT CODING STANDARDS ***
+
diff --git a/documentation/coding_standards/php_best_practices.txt b/documentation/coding_standards/php_best_practices.txt
new file mode 100644
index 000000000..9e4c63483
--- /dev/null
+++ b/documentation/coding_standards/php_best_practices.txt
@@ -0,0 +1 @@
+*** PHP BEST PRACTICES ***
diff --git a/documentation/coding_standards/php_coding_standards.txt b/documentation/coding_standards/php_coding_standards.txt
new file mode 100644
index 000000000..b7adc5dd9
--- /dev/null
+++ b/documentation/coding_standards/php_coding_standards.txt
@@ -0,0 +1,55 @@
+*** PHP CODING STANDARDS ***
+
+These are the coding standards for Elgg.  All core development and bundled
+plugins are required to be in this format. Plugin developers are strongly
+encouraged to adopt these standards.
+
+* 	Unix line endings.
+
+* 	Hard tabs, 4 character tab spacing.
+
+* 	No PHP shortcut tags ( <? or <?= or <% ).
+
+* 	PHPDoc comments on functions and classes (all methods; declared properties
+	when appropriate).
+
+* 	Mandatory wrapped {}s around any code blocks. 
+		Bad:
+		if (true) 
+			foreach($arr as $elem) 
+				echo $elem;
+	
+		Good:
+		if (true) {
+			foreach ($arr as $elem) {
+				echo $elem;
+			}
+		}
+
+* 	Name standalone functions using underscore_character().
+
+* 	Name classes using CamelCase() and methods using lowerCamelCase().
+
+* 	Name globals and constants in ALL_CAPS (ACCESS_FRIENDS, $CONFIG).
+
+* 	Use underscores / camel case to separate standard English words in
+	functions, classes, and methods. (get_default_site(), ElggUser->isLoggedIn()).
+
+* 	Space functions like_this($required, $optional = TRUE).
+
+* 	Space keywords and constructs like this: if (FALSE) { ... }.
+
+* 	Correctly use spaces, quotes, and {}s in strings: 
+		Bad (hard to read, misuse of quotes and {}s): 
+		echo 'Hello, '.$name."!  How is your {$time_of_day}?";
+		
+		Good:
+		echo "Hello, $name!  How is your $time_of_day?"; 
+
+* 	Line lengths should be reasonable.  If you are writing lines over 100 
+	characters on a line, please revise the code.
+
+* 	Use // or /* */ when commenting.
+
+* 	No closing PHP tag (?>) at EOF unless after a heredoc. (Avoids problems with 
+	trailing whitespace. Required after heredoc by PHP.)
-- 
cgit v1.2.3