Refs #2896: Added some initial CSS coding standards based on what I found/did in the last commit

git-svn-id: http://code.elgg.org/elgg/trunk@8704 36083f99-b078-4883-b0ff-0f9b5a30f544

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.