Skip to content

GitLab

javascript coding standards · Changes

Page history
rcabral created page: dependency-management authored by Rene Cabral's avatar Rene Cabral
Hide whitespace changes
Inline Side-by-side
javascript-coding-standards.markdown
View page @ 337d3e8f
......@@ -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. They are edited by Digitec when appropriate.__
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).
......@@ -177,9 +177,12 @@ 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.
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](http://javascript.crockford.com/private.html). Avoid conventions that demonstrate a lack of competence.
> __Digitec allows the sigil to be used, as a prefix in variable names, to denote jQuery references. It is valid usage according to the ecma 5.1 specification.__
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.
......@@ -193,30 +196,30 @@ Global variables should be in all caps. (JavaScript does not have macros or cons
#### 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.
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).
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).
- Braces should be used around all statements, even single statements, when they are part of a control structure, such as an if or for statement. This makes it easier to add statements without accidentally introducing bugs.
- 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).
- Braces should be used around all statements, even single statements, when they are part of a control structure, such as an `if` or `for` statement. This makes it easier to add statements without accidentally introducing bugs.
#### Labels
Statement labels are optional. Only these statements should be labeled: while, do, for, switch.
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.
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:
The `if` class of statements should have the following form:
```javascript
if (condition) {
......@@ -240,7 +243,7 @@ The if class of statements should have the following form:
#### for Statement
A for class of statements should have the following form:
A `for` class of statements should have the following form:
```javascript
for (initialization; condition; update) {
......@@ -256,7 +259,7 @@ A for class of statements should have the following form:
The first form should be used with arrays and with loops of a predeterminable number of iterations.
The second form should be used with objects. Be aware that members that are added to the prototype of the object will be included in the enumeration. It is wise to program defensively by using the hasOwnProperty method to distinguish the true members of the object:
The second form should be used with objects. Be aware that members that are added to the prototype of the object will be included in the enumeration. It is wise to program defensively by using the `hasOwnProperty` method to distinguish the true members of the object:
```javascript
for (variable in object) {
......@@ -268,7 +271,7 @@ The second form should be used with objects. Be aware that members that are adde
#### while Statement
A while statement should have the following form:
A `while` statement should have the following form:
```javascript
while (condition) {
......@@ -278,7 +281,7 @@ A while statement should have the following form:
#### do Statement
A do statement should have the following form:
A `do` statement should have the following form:
```javascript
do {
......@@ -286,28 +289,30 @@ A do statement should have the following form:
} while (condition);
```
Unlike the other compound statements, the do statement always ends with a ; (semicolon).
Unlike the other compound statements, the `do` statement always ends with a `;` (semicolon).
#### switch Statement
A switch statement should have the following form:
A `switch` statement should have the following form:
```javascript
switch (expression) {
case expression:
statements
default:
statements
case expression:
statements
default:
statements
}
```
Each case is aligned with the switch. This avoids over-indentation.
~~Each `case` is aligned with the `switch`. This avoids over-indentation.~~
Each group of statements (except the default) should end with break, return, or throw. Do not fall through.
> __Each `case` should be indented 4 spaces from the `switch`__
Each group of statements (except the `default`) should end with `break`, `return`, or `throw`. Do not fall through.
#### try Statement
The try class of statements should have the following form:
The `try` class of statements should have the following form:
```javascript
try {
......@@ -327,11 +332,11 @@ The try class of statements should have the following form:
#### continue Statement
Avoid use of the continue statement. It tends to obscure the control flow of the function.
Avoid use of the `continue` statement. It tends to obscure the control flow of the function.
#### with Statement
The with statement [should not be used](http://yuiblog.com/blog/2006/04/11/with-statement-considered-harmful/).
The `with` statement [should not be used](http://yuiblog.com/blog/2006/04/11/with-statement-considered-harmful/).
### Whitespace
......@@ -339,25 +344,29 @@ Blank lines improve readability by setting off sections of code that are logical
Blank spaces should be used in the following circumstances:
A keyword followed by ( (left parenthesis) should be separated by a space.
A keyword followed by `(` (left parenthesis) should be separated by a space.
```javascript
while (true) {
A blank space should not be used between a function value and its ( (left parenthesis). This helps to distinguish between keywords and function invocations.
All binary operators except . (period) and ( (left parenthesis) and [ (left bracket) should be separated from their operands by a space.
No space should separate a unary operator and its operand except when the operator is a word such as typeof.
Each ; (semicolon) in the control part of a for statement should be followed with a space.
Whitespace should follow every , (comma).
```
A blank space should not be used between a function value and its `(` (left parenthesis). This helps to distinguish between keywords and function invocations.
All binary operators except `.` (period) and `(` (left parenthesis) and `[` (left bracket) should be separated from their operands by a space.
No space should separate a unary operator and its operand except when the operator is a word such as `typeof`.
Each `;` (semicolon) in the control part of a `for` statement should be followed with a space.
Whitespace should follow every `,` (comma).
### Bonus Suggestions
#### {} and []
Use {} instead of new Object(). Use [] instead of new Array().
Use `{}` instead of `new Object()`. Use `[]` instead of `new Array()`.
Use arrays when the member names would be sequential integers. Use objects when the member names are arbitrary strings or names.
#### , (comma) Operator
Avoid the use of the comma operator except for very disciplined use in the control part of for statements. (This does not apply to the comma separator, which is used in object literals, array literals, var statements, and parameter lists.)
Avoid the use of the comma operator except for very disciplined use in the control part of `for` statements. (This does not apply to the comma separator, which is used in object literals, array literals, var statements, and parameter lists.)
#### Block Scope
......@@ -365,7 +374,7 @@ In JavaScript blocks do not have scope. Only functions have scope. Do not use bl
#### Assignment Expressions
Avoid doing assignments in the condition part of if and while statements.
Avoid doing assignments in the condition part of `if` and `while` statements.
Is
......@@ -382,23 +391,29 @@ intended? Avoid constructs that cannot easily be determined to be correct.
#### === and !== Operators.
It is almost always better to use the === and !== operators. The == and != operators do type coercion. In particular, do not use == to compare against falsy values.
It is almost always better to use the `===` and `!==` operators. The `==` and `!=` operators do type coercion. In particular, do not use `==` to compare against falsy values.
#### Confusing Pluses and Minuses
Be careful to not follow a + with + or ++. This pattern can be confusing. Insert parens between them to make your intention clear.
Be careful to not follow a `+` with `+` or `++`. This pattern can be confusing. Insert parens between them to make your intention clear.
```javascript
total = subtotal + +myInput.value;
```
is better written as
```javascript
total = subtotal + (+myInput.value);
so that the + + is not misread as ++.
```
so that the `+ +` is not misread as `++`.
#### eval is Evil
The eval function is the most misused feature of JavaScript. Avoid it.
The `eval` function is the most misused feature of JavaScript. Avoid it.
eval has aliases. Do not use the Function constructor. Do not pass strings to setTimeout or setInterval.
`eval` has aliases. Do not use the `Function` constructor. Do not pass strings to `setTimeout` or `setInterval`.
......@@ -407,3 +422,4 @@ eval has aliases. Do not use the Function constructor. Do not pass strings to se
[Code Conventions for the JavaScript Programming Language](http://javascript.crockford.com/code.html)
[ECMAScript Language Specification](wiki-assets/files/specification/Ecma-262.pdf)