aboutsummaryrefslogtreecommitdiff
path: root/CODING.txt
diff options
context:
space:
mode:
Diffstat (limited to 'CODING.txt')
-rw-r--r--CODING.txt223
1 files changed, 1 insertions, 222 deletions
diff --git a/CODING.txt b/CODING.txt
index 355601720..1cfd58dba 100644
--- a/CODING.txt
+++ b/CODING.txt
@@ -1,222 +1 @@
-*** 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.
+See documentation/coding_standards/