Merged r6534-6559 from 1.7 branch to trunk

git-svn-id: http://code.elgg.org/elgg/trunk@6840 36083f99-b078-4883-b0ff-0f9b5a30f544

1 files changed, 45 insertions, 17 deletions

diff --git a/CODING.txt b/CODING.txt
index b2224627f..3399d8e2f 100644
--- a/CODING.txt
+++ b/CODING.txt
@@ -3,11 +3,15 @@
 These are the coding standards for Elgg.  All core development, bundled 
 plugins, and tickets attached to Trac are expected to be in this format.
 
-* Unix line endings
+* Unix line endings.
+
 * Hard tabs, 4 character tab spacing.
-* No PHP shortcut tags ( <? or <?= or <% )
+
+* 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) 
@@ -20,22 +24,32 @@ plugins, and tickets attached to Trac are expected to be in this format.
 			echo $elem;
 		}
 	}
+
 * Name standalone functions using underscore_character().
+
 * Name classes using CamelCase() and methods using lowerCamelCase().
-* Name globals and constants in ALL_CAPS (FALSE, TRUE, NULL, ACCESS_FRIENDS, 
-  $CONFIG).
-* Space functions like_this($required, $optional = TRUE)
-* Space keywords and constructs like this: if (FALSE) { ... }
+
+* 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.)
 
@@ -51,18 +65,25 @@ work for developers, which means happier, more productive developers.
   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.
-* FALSE should be returned by functions on failure or error if not throwing an 
-  exception. 
+
+* Functions not throwing an exception on error should return FALSE upon 
+  failure. 
+
 * Functions returning only boolean should be prefaced with is_ or has_ (eg,
   is_logged_in(), 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:
+  describes the "how."  Ex:
 	Not a very useful comment:
 
 	// increment $i only when the entity is marked as active.
@@ -80,13 +101,14 @@ work for developers, which means happier, more productive developers.
 			$i++;
 		}
 	}
+
 * Use commit messages effectively.  Be concise and meaningful. Ex:
 	Not meaningful:
 	Small fix to groups.
 
 	Meaningful:
-	Fixes #1234: Missing ) was causing WSOD on group profile page when
-	logged out.
+	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.
@@ -101,24 +123,30 @@ indefinitely as plugin authors are expected to properly update their
 plugins.  In order to maintain backward compatibility, deprecated APIs will
 follow these guidelines:
 
-* API changes cannot occur between bugfix versions (1.6.0 - 1.6.1).
+* 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 procedures for deprecating an API are as follows:
+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 wrapper function will elgg_deprecated_notice('...', 1.7) to log
+  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
-  wrapper, but elgg_deprecated_notice() will produce a visible warning.
-* The third minor version (1.9) removes the wrapper function.  Any use of 
+  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.