diff options
author | cash <cash.costello@gmail.com> | 2011-07-03 08:58:58 -0400 |
---|---|---|
committer | cash <cash.costello@gmail.com> | 2011-07-03 08:58:58 -0400 |
commit | 807ae30cb037b827319b924994952daf57db2a40 (patch) | |
tree | 4177ddaa4727a8f9b7b3f0bc1a31e4dd161a92f9 /documentation/coding_standards/best_practices.txt | |
parent | d2c9e39308cfd64ca8a6487aac8e0d44a4e406c9 (diff) | |
download | elgg-807ae30cb037b827319b924994952daf57db2a40.tar.gz elgg-807ae30cb037b827319b924994952daf57db2a40.tar.bz2 |
separate out coding standards
Diffstat (limited to 'documentation/coding_standards/best_practices.txt')
-rw-r--r-- | documentation/coding_standards/best_practices.txt | 96 |
1 files changed, 96 insertions, 0 deletions
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. |