Javascript Guideline¶
File name¶
File names must be all lowercase and may include underscores _ or dashes -, but no additional punctuation.
Tab character¶
Tab characters are not used for indentation.
Braces are used for all control structures¶
Braces are required for all control structures (i.e. if, else, for, do, while, as well as any others), even if the body contains only a single statement. The first statement of a non-empty block must begin on its own line.
# Illegal:
if (someVeryLongCondition())
doSomething();
for (let i = 0; i < foo.length; i++) bar(foo[i]);
Exception: A simple if statement that can fit entirely on a single line with no wrapping (and that doesn’t have an else) may be kept on a single line with no braces when it improves readability. This is the only case in which a control structure may omit braces and newlines.
if (shortCondition()) return;
Use const and let¶
Declare all local variables with either const or let.
Use const by default, unless a variable needs to be reassigned. The var keyword must not be used.
One variable per declaration¶
Every local variable declaration declares only one variable: declarations such as let a = 1, b = 2; are not used.
Destructuring¶
Array literals may be used on the left-hand side of an assignment to perform destructuring (such as when unpacking multiple values from a single array or iterable). A final rest element may be included (with no space between the ... and the variable name). Elements should be omitted if they are unused.
const [a, b, c, ...rest] = generateResults();
let [, b,, d] = someArray;
// Destructuring may also be used for function parameters (note that a parameter name is required but ignored). Always specify [] as the default value if a destructured array parameter is optional, and provide default values on the left hand side:
/** @param {!Array<number>=} param1 */
function optionalDestructuring([a = 4, b = 2] = []) { … };
Do not use the Object constructor¶
While Object does not have the same problems as Array, it is still disallowed for consistency. Use an object literal ({} or {a: 0, b: 1, c: 2}) instead.
Shorthand properties¶
Shorthand properties are allowed on object literals.
Example:
const foo = 1;
const bar = 2;
const obj = {
foo,
bar,
method() { return this.foo + this.bar; },
};
assertEquals(3, obj.method());
Destructuring¶
Object destructuring patterns may be used on the left-hand side of an assignment to perform destructuring and unpack multiple values from a single object.
Destructured objects may also be used as function parameters, but should be kept as simple as possible: a single level of unquoted shorthand properties. Deeper levels of nesting and computed properties may not be used in parameter destructuring. Specify any default values in the left-hand-side of the destructured parameter ({str = 'some default'} = {}, rather than {str} = {str: 'some default'}), and if a destructured object is itself optional, it must default to {}. The JSDoc for the destructured parameter may be given any name (the name is unused but is required by the compiler).
Example:
/**
* @param {string} ordinary
* @param {{num: (number|undefined), str: (string|undefined)}=} param1
* num: The number of times to do something.
* str: A string to do stuff to.
*/
function destructured(ordinary, {num, str = 'some default'} = {})
Enums¶
Enumerations are defined by adding the @enum annotation to an object literal. Additional properties may not be added to an enum after it is defined. Enums must be constant, and all enum values must be deeply immutable.
/**
* Supported temperature scales.
* @enum {string}
*/
const TemperatureScale = {
CELSIUS: 'celsius',
FAHRENHEIT: 'fahrenheit',
};
/**
* An enum with two options.
* @enum {number}
*/
const Option = {
/** The option used shall have been the first. */
FIRST_OPTION: 1,
/** The second among two options. */
SECOND_OPTION: 2,
};
Getters and Setters¶
Do not use JavaScript getter and setter properties. They are potentially surprising and difficult to reason about, and have limited support in the compiler. Provide ordinary methods instead
Overriding toString¶
The toString method may be overridden, but must always succeed and never have visible side effects.
Arrow functions¶
Arrow functions provide a concise syntax and fix a number of difficulties with this. Prefer arrow functions over the function keyword, particularly for nested functions
class obj {
method() => {
}
}
Rest parameters¶
Use a rest parameter instead of accessing arguments. Rest parameters are typed with a ... prefix in their JSDoc. The rest parameter must be the last parameter in the list.
There is no space between the ... and the parameter name. Do not name the rest parameter var_args.
Never name a local variable or parameter arguments, which confusingly shadows the built-in name.
Example:
/**
* @param {!Array<string>} array This is an ordinary parameter.
* @param {...number} numbers The remainder of arguments are all numbers.
*/
function variadic(array, ...numbers) {}
Use single quotes¶
Ordinary string literals are delimited with single quotes ('), rather than double quotes (").
Tip
if a string contains a single quote character, consider using a template string to avoid having to escape the quote.
Exceptions¶
Exceptions are an important part of the language and should be used whenever exceptional cases occur. Always throw Errors or subclasses of Error: never throw string literals or other objects.
Always use new when constructing an Error.
Custom exceptions provide a great way to convey additional error information from functions. They should be defined and used wherever the native Error type is insufficient.
Package names¶
Package names are all lowerCamelCase. For example, my.exampleCode.deepSpace,
but not my.examplecode.deepspace or my.example_code.deep_space.
Class names¶
Class, interface, record, and typedef names are written in UpperCamelCase. Unexported classes are simply locals: they are not marked @private and therefore are not named with a trailing underscore.
Type names are typically nouns or noun phrases. For example, Request, ImmutableList, or VisibilityMode. Additionally, interface names may sometimes be adjectives or adjective phrases instead (for example, Readable).
Method names¶
Method names are written in lowerCamelCase. Private methods’ names must end with a trailing underscore.
Method names are typically verbs or verb phrases. For example, sendMessage or stop_. Getter and setter methods for properties are never required, but if they are used they should be named getFoo (or optionally isFoo or hasFoo for booleans),
or setFoo(value) for setters.
Underscores may also appear in JsUnit test method names to separate logical components of the name.
One typical pattern is test<MethodUnderTest>_<state>, for example testPop_emptyStack. There is no One Correct Way to name test methods.
Enum names¶
Enum names are written in UpperCamelCase, similar to classes, and should generally be singular nouns. Individual items within the enum are named in CONSTANT_CASE.
Constant names¶
Constant names use CONSTANT_CASE: all uppercase letters, with words separated by underscores. There is no reason for a constant to be named with a trailing underscore, since private static properties can be replaced by (implicitly private) module locals.
Variable names¶
Local variable and parameter names are written in lowerCamelCase
Camel case: defined¶
Sometimes there is more than one reasonable way to convert an English phrase into camel case, such as when acronyms or unusual constructs like IPv6 or iOS are present. To improve predictability, Google Style specifies the following (nearly) deterministic scheme.
Beginning with the prose form of the name:
- Convert the phrase to plain ASCII and remove any apostrophes. For example, Müller's algorithm might become Muellers algorithm.
- Divide this result into words, splitting on spaces and any remaining punctuation (typically hyphens).
- Recommended: if any word already has a conventional camel case appearance in common usage, split this into its constituent parts (e.g., AdWords becomes ad words). Note that a word such as iOS is not really in camel case per se; it defies any convention, so this recommendation does not apply.
-
Now lowercase everything (including acronyms), then uppercase only the first character of:
- … each word, to yield upper camel case, or
- … each word except the first, to yield lower camel case
-
Finally, join all the words into a single identifier.
the casing of the original words is almost entirely disregarded.
Examples:
| Prose form | Correct | Incorrect |
|---|---|---|
| XML HTTP request | XmlHttpRequest | XMLHTTPRequest |
| new customer ID | newCustomerId | newCustomerID |
| inner stopwatch | innerStopwatch | innerStopWatch |
| supports IPv6 on iOS? | supportsIpv6OnIos | supportsIPv6OnIOS |
| YouTube importer | YouTubeImporter | YoutubeImporter* |
*Acceptable, but not recommended.
JSDoc¶
JSDoc is used on all classes, fields, and methods.