Linting
Use JSHint to detect errors and potential problems. Every jQuery project has a Grunt task for linting all JavaScript files: grunt jshint
. The options for JSHint are stored in a .jshintrc
file; many repositories will have multiple .jshintrc
files based on the type of code in each directory.
Each .jshintrc
file follows a specific format. All options must be alphabetized and grouped:
1
2
3
4
5
6
7
8
9
10
11
12
|
|
The following common options must be used in all projects:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
|
If the project supports browsers which do not implement ES5, then the es3
option must be included with the repo-specific options.
Spacing
In general, the jQuery style guide encourages liberal spacing for improved human readability. The minification process creates a file that is optimized for browsers to read and process.
- Indentation with tabs.
- No whitespace at the end of line or on blank lines.
- Lines should be no longer than 80 characters, and must not exceed 100 (counting tabs as 4 spaces). There are 2 exceptions, both allowing the line to exceed 100 characters:
- If the line contains a comment with a long URL.
- If the line contains a regex literal. This prevents having to use the regex constructor which requires otherwise unnecessary string escaping.
-
if
/else
/for
/while
/try
always have braces and always go on multiple lines. - Unary special-character operators (e.g.,
!
,++
) must not have space next to their operand. - Any
,
and;
must not have preceding space. - Any
;
used as a statement terminator must be at the end of the line. - Any
:
after a property name in an object definition must not have preceding space. - The
?
and:
in a ternary conditional must have space on both sides. - No filler spaces in empty constructs (e.g.,
{}
,[]
,fn()
) - New line at the end of each file.
- If the entire file is wrapped in a closure, the function body is not indented. See full file closures for examples.
Bad Examples
1
2
3
4
// Bad
if(condition) doSomething();
while(!condition) iterating++;
for(var i=0;i<100;i++) object[array[i]] = someFn(i);
1
2
3
4
|
|
Good Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var i = 0;
if ( condition ) {
doSomething();
} else if ( otherCondition ) {
somethingElse();
} else {
otherThing();
}
while ( !condition ) {
iterating++;
}
for ( ; i < 100; i++ ) {
object[ array[ i ] ] = someFn( i );
}
try {
// Expressions
} catch ( e ) {
// Expressions
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
|
Objects
Object declarations can be made on a single line if they are short (remember the line length limits). When an object declaration is too long to fit on one line, there must be one property per line. Property names only need to be quoted if they are reserved words or contain special characters:
1
2
3
4
5
6
7
8
9
10
11
12
13
|
|
Arrays and Function Calls
Always include extra spaces around elements and arguments:
1
2
3
4
5
6
7
8
9
10
11
12
13
|
|
Exceptions:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
|
Multi-line Statements
When a statement is too long to fit on one line, line breaks must occur after an operator.
1
2
3
4
5
6
7
|
|
Lines should be broken into logical groups if it improves readability, such as splitting each expression of a ternary operator onto its own line even if both will fit on a single line.
1
2
3
|
|
When a conditional is too long to fit on one line, successive lines must be indented one extra level to distinguish them from the body.
1
2
3
4
|
|
Chained Method Calls
When a chain of method calls is too long to fit on one line, there must be one call per line, with the first call on a separate line from the object the methods are called on. If the method changes the context, an extra level of indentation must be used.
1
2
3
4
5
6
|
|
Full File Closures
When an entire file is wrapped in a closure, the body of the closure is not indented.
1
2
3
4
5
|
|
The same applies to AMD wrappers.
1
2
3
4
5
6
7
8
9
|
|
For UMD, the factory is indented to visually differentiate it from the body.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
|
|
Assignments
Assignments in a declaration must be on their own line. Declarations that don't have an assignment must be listed together at the start of the declaration. Each line after the initial line must be indented once. For example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
|
Exception: When a declaration has a single multiline assignment, the subsequent lines are not indented.
1
2
3
4
5
6
7
8
9
|
|
Equality
Strict equality checks (===
) must be used in favor of abstract equality checks (==
). The only exception is when checking for undefined
and null
by way of null
.
1
2
|
|
Type Checks
- String:
typeof object === "string"
- Number:
typeof object === "number"
- Boolean:
typeof object === "boolean"
- Object:
typeof object === "object"
- Plain Object:
jQuery.isPlainObject( object )
- Function:
jQuery.isFunction( object )
- Array:
jQuery.isArray( object )
- Element:
object.nodeType
- null:
object === null
- null or undefined:
object == null
- undefined:
- Global Variables:
typeof variable === "undefined"
- Local Variables:
variable === undefined
- Properties:
object.prop === undefined
typeof object === "string"
typeof object === "number"
typeof object === "boolean"
typeof object === "object"
jQuery.isPlainObject( object )
jQuery.isFunction( object )
jQuery.isArray( object )
object.nodeType
object === null
object == null
- Global Variables:
typeof variable === "undefined"
- Local Variables:
variable === undefined
- Properties:
object.prop === undefined
Comments
Comments are always preceded by a blank line. Comments start with a capital first letter, but don't require a period at the end, unless you're writing full sentences. There must be a single space between the comment token and the comment text.
Single line comments go over the line they refer to:
1
2
3
4
5
6
|
|
Multi-line comments are only used for file and function headers.
Inline comments are allowed as an exception when used to annotate special arguments in formal parameter lists or when needed to support a specific development tool:
1
2
3
|
|
Do not write API documentation in comments. API documentation lives in its own repository.
Quotes
jQuery uses double quotes.
1
|
|
Strings that require inner quoting must use double outside and single inside.
1
|
|
Semicolons
Use them. Never rely on ASI.
Naming Conventions
Variable and function names should be full words, using camel case with a lowercase first letter. Names should be descriptive but not excessively so. Exceptions are allowed for iterators, such as the use of i
to represent the index in a loop. Constructors do not need a capital first letter.
Global Variables
Each project may expose at most one global variable.
DOM Node Rules
.nodeName
must always be used in favor of .tagName
.
.nodeType
must be used to determine the classification of a node (not .nodeName
).
Switch Statements
The usage of switch
statements is generally discouraged, but can be useful when there are a large number of cases - especially when multiple cases can be handled by the same block, or fall-through logic (the default
case) can be leveraged.
When using switch
statements:
- Use a
break
for each case other thandefault
. - Align
case
statements with theswitch
.
1
2
3
4
5
6
7
8
9
10
11
|
|