aboutsummaryrefslogtreecommitdiff
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/coding_standards/best_practices.txt96
-rw-r--r--documentation/coding_standards/css_coding_standards.txt67
-rw-r--r--documentation/coding_standards/html_best_practices.txt1
-rw-r--r--documentation/coding_standards/javascript_best_practices.txt1
-rw-r--r--documentation/coding_standards/javascript_coding_standards.txt2
-rw-r--r--documentation/coding_standards/php_best_practices.txt1
-rw-r--r--documentation/coding_standards/php_coding_standards.txt55
7 files changed, 223 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.
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.)