aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--CODING.txt116
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.