Use RFC 2119 to interpret the “must,” “must not,” “required,” “shall,” “shall not,” “should,” “should not,” “recommended,” “may,” and “optional” keywords.
Eslint and JSCS tools
Additional formatting standards
Anonymous function calls
When you declare an anonymous function as an argument in a function call, indent the body of the function by four spaces from the left edge of the statement or function keyword to increase readability.
End of file
The last line in a file must end with a single linefeed(LF) character(i.e. an empty line).
This reduces the quantity of the changed lines in a diff and makes code safer in file concatenation processes.
Indentation in Magento code uses two spaces.
Tabs are not allowed as indentation.
Indent wrapped lines two spaces or left-aligned to the expression above.
Max line length
The recommended max line length is 80 characters.
Source code lines must not exceed 120 characters.
Comment lines that contain an example command or a literal URL longer than 120 characters may exceed the 120 character limit for ease of cutting and pasting.
Do not be concerned about header guards that exceed 120 characters.
Line termination follows the UNIX text file convention.
Lines must end with a single linefeed(LF) character represented as ordinal 10 or hexadecimal (
Do not use carriage the Mac OS convention of carriage returns(CR or
0x0D) or the carriage return-linefeed combination(CRLF or
0x0A) standard for Windows OS.
Multi-line string literals
Use string concatenation for multi-line string literals:
Use sparingly and in general where required by the syntax and semantics.
Never use parentheses for:
- Unary operators (e.g.
- After keywords such as
new, and others keywords like them
Use braces with all multiline blocks. May only omit braces if entire block can be written in one line and improves readability.
Always put semicolons as statement terminators.
The following code examples show the dangers of missing semicolons:
Since there is semicolon to end the first statement, the first function returns 42 and the script interprets 42 as a function. When the script tries to call 42 as a function with the second function as a parameter, an error occurs.
A ‘no such property in undefined’ error appears during runtime when the script tries to call
The script calls
NaN and assigns
THING_TO_EAT the result of
In each of the examples above, a function declaration, or an object, or an array literal is used inside a statement.
Use single quotes instead of double quotes for consistency.
This is helpful when creating strings that include HTML:
Additional naming convention standards
General naming conventions
- Avoid underscores and numbers in names.
- Variables or methods should have names that accurately describe their purpose or behavior.
- Object methods or variables that are declared
protectedshould start with an underscore(
Functions and methods
- Class method names should start with an English verb in its infinitive form that describes the method.
- Names for accessors for instance or static variables should always have the
- In design pattern classes, implementation method names should contain the pattern name where practical to provide better behavior description.
- Methods that return status flags or Boolean values should have the
Variables and properties
- Do not use short variable names such as
nexcept in small loop contexts
- If a loop contains more than 20 lines of code, the index variables should have more descriptive names.
Additional coding construct standards
Binary and ternary operators
Always put the operator on the preceding line to avoid implicit semi-colon insertion issues.
This method must always succeed without side effects.
Function declarations within blocks
Use a variable initialized with a function expression to define a function within a block.
Exceptions and custom exceptions
You cannot avoid exceptions if you are doing something non-trivial (using an application development framework, and so on).
Without custom exceptions, returning error information from a function that also returns a value can be tricky, not to mention inelegant. Bad solutions include passing in a reference type to hold error information or always returning Objects with a potential error member.
These basically amount to a primitive exception handling hack. Feel free to use custom exceptions when appropriate.
For maximum portability and compatibility, use standard features whenever possible.
string.charAt(3) instead of
string, and element access with DOM functions instead of using an application-specific shorthand.
There are several ways to attach methods and properties to a constructor, but the preferred style is:
Do not use:
A closure keeps a pointer to its enclosing scope, so attaching a closure to a DOM element can create a circular reference and thus, a memory leak.
The function closure keeps references to elements “a” and “b” even if it never uses them.
Because elements also keep references to the closure, it is a cycle that will not be cleaned up by garbage collection. In these situations, the code can be structured as follows:
Additional general standards
Array and object initializers
Single-line array and object initializers are allowed when they fit on a line as follows:
Long identifiers or values present problems for aligned initialization lists, so always prefer non-aligned initialization.
Object instead of
Array for associative arrays.
Use deferred initialization when it is not possible to initialize variables at the point of declaration.
Use explicit scope to increase code portability and clarity.
Modifying built-in like
Array.prototype is strictly forbidden.
Modifying other built-ins like
Function.prototype is less dangerous but leads to debugging issue in production.
Declare a variable with
var wherever possible to avoid overwriting existing global values.
Using only one var per scope promotes readability.