diff options
| -rw-r--r-- | CODING.txt | 222 | ||||
| -rw-r--r-- | documentation/coding_standards/best_practices.txt | 58 | ||||
| -rw-r--r-- | documentation/coding_standards/css_coding_standards.txt | 67 | ||||
| -rw-r--r-- | documentation/coding_standards/deprecation.txt | 36 | ||||
| -rw-r--r-- | documentation/coding_standards/html_best_practices.txt | 1 | ||||
| -rw-r--r-- | documentation/coding_standards/javascript_best_practices.txt | 1 | ||||
| -rw-r--r-- | documentation/coding_standards/javascript_coding_standards.txt | 2 | ||||
| -rw-r--r-- | documentation/coding_standards/php_best_practices.txt | 1 | ||||
| -rw-r--r-- | documentation/coding_standards/php_coding_standards.txt | 55 |
9 files changed, 221 insertions, 222 deletions
diff --git a/CODING.txt b/CODING.txt deleted file mode 100644 index 355601720..000000000 --- a/CODING.txt +++ /dev/null @@ -1,222 +0,0 @@ -*** 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. 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.) |