diff options
| -rw-r--r-- | CODING.txt | 116 |
1 files changed, 92 insertions, 24 deletions
diff --git a/CODING.txt b/CODING.txt index 3399d8e2f..e9a1f5fb5 100644 --- a/CODING.txt +++ b/CODING.txt @@ -10,7 +10,7 @@ plugins, and tickets attached to Trac are expected to be in this format. * No PHP shortcut tags ( <? or <?= or <% ). * PHPDoc comments on functions and classes (all methods; declared properties - when appropriate). +when appropriate). * Mandatory wrapped {}s around any code blocks. Bad: @@ -32,7 +32,7 @@ plugins, and tickets attached to Trac are expected to be in this format. * 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()). +functions, classes, and methods. (get_default_site(), ElggUser->isLoggedIn()). * Space functions like_this($required, $optional = TRUE). @@ -46,12 +46,80 @@ plugins, and tickets attached to Trac are expected to be in this format. 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. +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.) +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 *** @@ -61,29 +129,29 @@ 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. +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 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. +on no results. * Functions not throwing an exception on error should return FALSE upon - failure. +failure. * Functions returning only boolean should be prefaced with is_ or has_ (eg, - is_logged_in(), has_access_to_entity()). +is_logged_in(), 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: +describes the "how." Ex: Not a very useful comment: // increment $i only when the entity is marked as active. @@ -111,7 +179,7 @@ work for developers, which means happier, more productive developers. when logged out. * Commit effectively: Err on the side of atomic commits. One revision with - many changes is scary. +many changes is scary. *** DEPRECATING APIs *** @@ -124,29 +192,29 @@ 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). +(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.) +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. +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. +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. +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 deprecated API should be corrected before this. The general timeline for two minor releases is 8 to 12 months. |