*** 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.

* Unix line endings
* Hard tabs, 4 character tab spacing.
* No shortcut tags ( <? or <?= or <% )
* PHPDoc comments on functions and classes (including methods and declared 
  members).
* 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 (FALSE, TRUE, NULL, ACCESS_FRIENDS, 
  $CONFIG).
* Space functions like_this($required, $optional = TRUE)
* Space keywords and constructs like this: if (false) { ... }
* Include variables in strings with double quotes instead of concatenating:
	Bad: 
	echo 'Hello, ' . $name . '!  How are you?';
	
	Good:
	echo "Hello, $name!  How are you?"; 
	
* Line lengths should be reasonable.  If you are writing lines over 100 
  characters, please revise the code.
* Use slash-style comments. (// and /* */)
* Preferred no closing ?> tag at EOF. (Avoids problems with trailing 
  whitespace, marginal speed improvements.)


*** 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:

* 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.  (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 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 use elgg_log('...', 'WARNING') to announce
  that the function is deprecated.
* The second minor version (1.8) maintains the backward compatibility
  wrapper, but in addition to elgg_log(), a register_error() message is also
  thrown.
* The third minor version (1.9) removes the wrapper function.  Any use of 
  the deprecated API should be corrected before this.

The general timeline for three minor releases is 8 to 12 months.


*** 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.

* 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.
* If not throwing an exception, boolean FALSE should be returned by functions
  on failure or error.
* Functions returning only boolean should be prefaced with is_*(). (eg,
  is_logged_in().)
* 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++;
		}
	}
* Commit effectively: Err on the side of atomic commits.  One revision with
  many changes is scary.
* Commit effectively part 2: Use concise, meaningful commit messages. Ex:
	Not meaningful: "Fixed some bugs in groups."
	Meaningful: "Fixes #1234: Missing ) added in group profile page."