diff options
Diffstat (limited to 'documentation')
8 files changed, 221 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. 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/deprecation.txt b/documentation/coding_standards/deprecation.txt new file mode 100644 index 000000000..370090138 --- /dev/null +++ b/documentation/coding_standards/deprecation.txt @@ -0,0 +1,36 @@ +*** 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/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.) |