javascript-coding-standards.markdown

@@ -9,7 +9,7 @@
 ## Code Conventions for the JavaScript Programming Language
 
 
-> The php standards should be observed in conjunction with the javascript conventions, but the javascript conventions are to be preferred when there is overlap. The javascript conventions are borrowed from Douglas Crockford.
+`The php standards should be observed in conjunction with the javascript conventions, but the javascript conventions are to be preferred when there is overlap. The javascript conventions are borrowed from Douglas Crockford.`
 
 
 This is a set of coding conventions and rules for use in JavaScript programming. It is inspired by the [Sun](http://www.sun.com/) document [Code Conventions for the Java Programming Language](http://java.sun.com/docs/codeconv/). It is heavily modified of course because [JavaScript is not Java](http://javascript.crockford.com/javascript.html).
@@ -60,7 +60,7 @@ Generally use line comments. Save block comments for formal documentation and fo
 
 ### Variable Declarations
 
-All variables should be declared before used. JavaScript does not require this, but doing so makes the program easier to read and makes it easier to detect undeclared variables that may become implied globals. Implied global variables should never be used.
+All variables should be declared before used. JavaScript does not require this, but doing so makes the program easier to read and makes it easier to detect undeclared variables that may become implied [globals](http://yuiblog.com/blog/2006/06/01/global-domination/). Implied global variables should never be used.
 
 The var statements should be the first statements in the function body.
 
@@ -79,9 +79,9 @@ Use of global variables should be minimized. Implied global variables should nev
 
 ### Function Declarations
 
-All functions should be declared before they are used. Inner functions should follow the var statement. This helps make it clear what variables are included in its scope.
+All functions should be declared before they are used. Inner functions should follow the `var` statement. This helps make it clear what variables are included in its scope.
 
-There should be no space between the name of a function and the ( (left parenthesis) of its parameter list. There should be one space between the ) (right parenthesis) and the { (left curly brace) that begins the statement body. The body itself is indented four spaces. The } (right curly brace) is aligned with the line containing the beginning of the declaration of the function.
+There should be no space between the name of a function and the `(` (left parenthesis) of its parameter list. There should be one space between the `)` (right parenthesis) and the `{` (left curly brace) that begins the statement body. The body itself is indented four spaces. The `}` (right curly brace) is aligned with the line containing the beginning of the declaration of the function.
 
 ```javascript
 
@@ -124,16 +124,14 @@ This convention works well with JavaScript because in JavaScript, functions and
         return results;
     }
 ```
-If a function literal is anonymous, there should be one space between the word function and the ( (left parenthesis). If the space is omited, then it can appear that the function's name is function, which is an incorrect reading.
+
+If a function literal is anonymous, there should be one space between the word `function` and the `(` (left parenthesis). If the space is omited, then it can appear that the function's name is `function`, which is an incorrect reading.
 
 ```javascript
     div.onclick = function (e) {
         return false;
     };
 
-
-
-
     that = {
         method: function () {
             return this.datum;
@@ -141,22 +139,16 @@ If a function literal is anonymous, there should be one space between the word f
         datum: 0
     };
 ```
-Use of global functions should be minimized.
-
-
 
+Use of global functions should be minimized.
 
 When a function is to be invoked immediately, the entire invocation expression should be wrapped in parens so that it is clear that the value being produced is the result of the function and not the function itself.
 
-
 ```javascript
 
 var collection = (function () {
     var keys = [], values = [];
 
-
-
-
     return {
         get: function (key) {
             var at = keys.indexOf(key);
@@ -185,64 +177,30 @@ var collection = (function () {
 
 ### Names
 
-
-
-
 Names should be formed from the 26 upper and lower case letters (A .. Z, a .. z), the 10 digits (0 .. 9), and _ (underbar). Avoid use of international characters because they may not read well or be understood everywhere. Do not use $ (dollar sign) or \ (backslash) in names.
 
-
-
-
-Do not use _ (underbar) as the first character of a name. It is sometimes used to indicate privacy, but it does not actually provide privacy. If privacy is important, use the forms that provide private members. Avoid conventions that demonstrate a lack of competence.
-
-
-
+Do not use _ (underbar) as the first character of a name. It is sometimes used to indicate privacy, but it does not actually provide privacy. If privacy is important, use the forms that provide [private members](http://javascript.crockford.com/private.html). Avoid conventions that demonstrate a lack of competence.
 
 Most variables and functions should start with a lower case letter.
 
-
-
-
-Constructor functions which must be used with the new prefix should start with a capital letter. JavaScript issues neither a compile-time warning nor a run-time warning if a required new is omitted. Bad things can happen if new is not used, so the capitalization convention is the only defense we have.
-
-
-
+Constructor functions which must be used with the [`new` prefix](http://yuiblog.com/blog/2006/11/13/javascript-we-hardly-new-ya/) should start with a capital letter. JavaScript issues neither a compile-time warning nor a run-time warning if a required `new` is omitted. Bad things can happen if `new` is not used, so the capitalization convention is the only defense we have.
 
 Global variables should be in all caps. (JavaScript does not have macros or constants, so there isn't much point in using all caps to signify features that JavaScript doesn't have.)
 
 
-
-
 ### Statements
 
 
-
-
 #### Simple Statements
 
-
-
-
 Each line should contain at most one statement. Put a ; (semicolon) at the end of every simple statement. Note that an assignment statement which is assigning a function literal or object literal is still an assignment statement and must end with a semicolon.
 
-
-
-
 JavaScript allows any expression to be used as a statement. This can mask some errors, particularly in the presence of semicolon insertion. The only expressions that should be used as statements are assignments and invocations.
 
-
-
-
 #### Compound Statements
 
-
-
-
 Compound statements are statements that contain lists of statements enclosed in { } (curly braces).
 
-
-
-
 - The enclosed statements should be indented four more spaces.
 - The { (left curly brace) should be at the end of the line that begins the compound statement.
 - The } (right curly brace) should begin a line and be indented to align with the beginning of the line containing the matching { (left curly brace).
@@ -250,23 +208,12 @@ Compound statements are statements that contain lists of statements enclosed in
 
 #### Labels
 
-
-
-
 Statement labels are optional. Only these statements should be labeled: while, do, for, switch.
 
-
-
-
 #### return Statement
 
-
-
-
 A return statement with a value should not use ( ) (parentheses) around the value. The return value expression must start on the same line as the return keyword in order to avoid semicolon insertion.
 
-
-
 #### if Statement
 
 The if class of statements should have the following form:
@@ -384,7 +331,7 @@ Avoid use of the continue statement. It tends to obscure the control flow of the
 
 #### with Statement
 
-The with statement should not be used.
+The with statement [should not be used](http://yuiblog.com/blog/2006/04/11/with-statement-considered-harmful/).
 
 ### Whitespace