diff options
| -rw-r--r-- | CODING.txt | 306 |
1 files changed, 154 insertions, 152 deletions
diff --git a/CODING.txt b/CODING.txt index e9a1f5fb5..355601720 100644 --- a/CODING.txt +++ b/CODING.txt @@ -3,123 +3,125 @@ These are the coding standards for Elgg. All core development, bundled plugins, and tickets attached to Trac are expected to be in this format. -* Unix line endings. +** PHP ** -* Hard tabs, 4 character tab spacing. +* Unix line endings. -* No PHP shortcut tags ( <? or <?= or <% ). +* Hard tabs, 4 character tab spacing. -* PHPDoc comments on functions and classes (all methods; declared properties -when appropriate). +* No PHP shortcut tags ( <? or <?= or <% ). -* Mandatory wrapped {}s around any code blocks. - Bad: - if (true) - foreach($arr as $elem) - echo $elem; +* PHPDoc comments on functions and classes (all methods; declared properties + when appropriate). - Good: - if (true) { - foreach($arr as $elem) { - echo $elem; +* 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 standalone functions using underscore_character(). -* Name classes using CamelCase() and methods using lowerCamelCase(). +* Name classes using CamelCase() and methods using lowerCamelCase(). -* Name globals and constants in ALL_CAPS (TRUE, NULL, ACCESS_FRIENDS, $CONFIG). +* 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()). +* 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 functions like_this($required, $optional = TRUE). -* Space keywords and constructs like this: if (FALSE) { ... }. +* 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?"; +* 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. +* Line lengths should be reasonable. If you are writing lines over 100 + characters on a line, please revise the code. -* Use // or /* */ when commenting. +* Use // or /* */ when commenting. -* No closing PHP tag (?>) at EOF unless after a heredoc. (Avoids problems with -trailing whitespace. Required after heredoc by PHP.) +* 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; +* 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 - Good: - border: 1px solid #999999; +* One property per line + Bad: + color: white;font-size: smaller; + + Good: + color: white; + font-size: smaller; - -webkit-border-radius: 5px; - -moz-border-radius: 5px; - border-radius: 5px; +* 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; + 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; +* 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 *** @@ -128,58 +130,58 @@ 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. +* 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. -* Use self-documenting variable names. $group_guids is better than $array. +* 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. -* Functions returning an array should return an empty array instead of FALSE -on no results. +* Use self-documenting variable names. $group_guids is better than $array. -* Functions not throwing an exception on error should return FALSE upon -failure. +* Functions returning an array should return an empty array instead of FALSE + on no results. -* Functions returning only boolean should be prefaced with is_ or has_ (eg, -is_logged_in(), has_access_to_entity()). +* Functions not throwing an exception on error should return FALSE upon + failure. -* Ternary syntax is acceptable for single-line, non-embedded statements. +* Functions returning only boolean should be prefaced with is_ or has_ (eg, + elgg_is_logged_in(), elgg_has_access_to_entity()). -* Use comments effectively. Good comments describe the "why." Good code -describes the "how." Ex: - Not a very useful comment: +* Ternary syntax is acceptable for single-line, non-embedded statements. - // increment $i only when the entity is marked as active. - foreach($entities as $entity) { - if ($entity->active == TRUE) { - $i++; +* 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++; + + 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. +* 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. +* Commit effectively: Err on the side of atomic commits. One revision with + many changes is scary. *** DEPRECATING APIs *** @@ -191,30 +193,30 @@ 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). +* 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.) +* 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. +* 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. +* 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 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 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 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. |