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 ***
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 ***
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.
projects / lorea / elgg.git / commitdiff