aboutsummaryrefslogtreecommitdiff
path: root/documentation/coding_standards/best_practices.txt
diff options
context:
space:
mode:
authorBrett Profitt <brett.profitt@gmail.com>2011-08-25 10:00:38 -0700
committerBrett Profitt <brett.profitt@gmail.com>2011-08-25 10:00:38 -0700
commitdccc333c765bb28da55b4a55d9c916acdb88413a (patch)
treebdd26a0b4cd85241a19b7fcb2c0770f0ac3eb9f0 /documentation/coding_standards/best_practices.txt
parentec7b94a64aef23b85866ecdac8e8acc712d29bb6 (diff)
parent003cb81c7888f4d2fd763e5814027c6f8d71186f (diff)
downloadelgg-dccc333c765bb28da55b4a55d9c916acdb88413a.tar.gz
elgg-dccc333c765bb28da55b4a55d9c916acdb88413a.tar.bz2
Merge branch 'master' of github.com:brettp/Elgg
Diffstat (limited to 'documentation/coding_standards/best_practices.txt')
-rw-r--r--documentation/coding_standards/best_practices.txt58
1 files changed, 58 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..069ac42aa
--- /dev/null
+++ b/documentation/coding_standards/best_practices.txt
@@ -0,0 +1,58 @@
+*** 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.