diff options
Diffstat (limited to 'CODING.txt')
-rw-r--r-- | CODING.txt | 223 |
1 files changed, 1 insertions, 222 deletions
diff --git a/CODING.txt b/CODING.txt index 355601720..1cfd58dba 100644 --- a/CODING.txt +++ b/CODING.txt @@ -1,222 +1 @@ -*** 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. - -** PHP ** - -* 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 (TRUE, NULL, 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.) - -** CSS ** - -* 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; - - -*** 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. +See documentation/coding_standards/ |