Lines Matching +full:exempt +full:- +full:issue +full:- +full:labels
4 <meta charset="utf-8">
23 well. However, this document focuses primarily on the hard-and-fast rules that
27 <h3 id="terminology-notes">1.1 Terminology notes</h3>
34 for both human-readable text and machine-readable annotations within
44 <h3 id="guide-notes">1.2 Guide notes</h3>
46 <p>Example code in this document is <strong>non-normative</strong>. That is, while the examples
51 <h2 id="source-file-basics">2 Source file basics</h2>
53 <h3 id="file-name">2.1 File name</h3>
56 (<code>-</code>), but no additional punctuation. Follow the convention that your project
59 <h3 id="file-encoding">2.2 File encoding: UTF-8</h3>
61 <p>Source files are encoded in <strong>UTF-8</strong>.</p>
63 <h3 id="special-characters">2.3 Special characters</h3>
65 <h4 id="whitespace-characters">2.3.1 Whitespace characters</h4>
76 <h4 id="special-escape-sequences">2.3.2 Special escape sequences</h4>
83 <h4 id="non-ascii-characters">2.3.3 Non-ASCII characters</h4>
85 <p>For the remaining non-ASCII characters, either the actual Unicode character
92 <pre><code class="language-js prettyprint">/* Best: perfectly clear even without a comment. */
98 /* Good: use escapes for non-printable characters with a comment for clarity. */
102 <pre><code class="language-js prettyprint badcode">/* Poor: the reader has no idea what character t…
107 might not handle non-ASCII characters properly. If that happens, those programs
110 <h2 id="source-file-structure">3 Source file structure</h2>
128 <h3 id="file-copyright">3.1 License or copyright information, if present</h3>
132 <h3 id="file-fileoverview">3.2 <code>@fileoverview</code> JSDoc, if present</h3>
134 <p>See <a href="#jsdoc-top-file-level-comments">??</a> for formatting rules.</p>
136 <h3 id="file-goog-module">3.3 <code>goog.module</code> statement</h3>
140 therefore an exception to the 80-column limit.</p>
149 <pre><code class="language-js prettyprint">goog.module('search.urlHistory.UrlHistoryService');
152 <h4 id="naming-hierarchy">3.3.1 Hierarchy</h4>
159 <pre><code class="language-js prettyprint badcode">goog.module('foo.bar'); // 'foo.bar.qux' would…
163 <p>The directory hierarchy reflects the namespace hierarchy, so that deeper-nested
164 children are subdirectories of higher-level parent directories. Note that this
168 <h4 id="file-declare-legacy-namespace">3.3.2 <code>goog.module.declareLegacyNamespace</code></h4>
176 <pre><code class="language-js prettyprint">goog.module('my.test.helpers');
182 traditional object hierarchy-based namespaces but comes with some naming
189 <h3 id="file-goog-module-exports">3.3.3 <code>goog.module</code> Exports</h3>
194 exported if they are meant to be used outside the module. Non-exported
195 module-local symbols are not declared <code>@private</code> nor do their names end with an
196 underscore. There is no prescribed ordering for exported and module-local
201 <pre><code class="language-js prettyprint">const /** !Array<number> */ exportedArray = [1, 2,…
218 <pre><code class="language-js prettyprint">/** @const {number} */
228 <pre><code class="language-js badcode prettyprint">/** @const */
232 <p><span id="file-es6-modules"></span></p>
234 <h3 id="file-es-modules">3.4 ES modules</h3>
236 <p><span id="es6-module-imports"></span></p>
238 <h4 id="es-module-imports">3.4.1 Imports</h4>
241 80-column limit.</p>
243 <p><span id="es6-import-paths"></span></p>
245 <h5 id="esm-import-paths">3.4.1.1 Import paths</h5>
250 <pre><code class="language-js prettyprint external">import './sideeffects.js';
258 <p><span id="es6-import-paths-file-extension"></span></p>
260 <h6 id="esm-import-paths-file-extension">3.4.1.1.1 File extensions in import paths</h6>
265 <pre><code class="language-js badcode prettyprint">import '../directory/file';
268 <pre><code class="language-js good prettyprint">import '../directory/file.js';
271 <h5 id="importing-the-same-file-multiple-times">3.4.1.2 Importing the same file multiple times</h5>
276 <pre><code class="language-js badcode prettyprint">// Imports have the same path, but since it does…
281 <p><span id="naming-es6-imports"></span></p>
283 <h5 id="naming-esm-imports">3.4.1.3 Naming imports</h5>
285 <h6 id="naming-module-imports">3.4.1.3.1 Naming module imports</h6>
290 <pre><code class="language-js prettyprint">import * as fileOne from '../file-one.js';
295 <pre><code class="language-js prettyprint">import * as libString from './lib/string.js';
300 <h6 id="naming-default-imports">3.4.1.3.2 Naming default imports</h6>
303 rules in <a href="#naming-rules-by-identifier-type">??</a>.</p>
305 <pre><code class="language-js prettyprint">import MyClass from '../my-class.js';
311 style guide, see <a href="#named-vs-default-exports">??</a>. Default imports are only used
314 <h6 id="naming-named-imports">3.4.1.3.3 Naming named imports</h6>
321 <pre><code class="language-js prettyprint">import * as bigAnimals from './biganimals.js';
331 <pre><code class="language-js prettyprint">import {Cat as BigCat} from './biganimals.js';
338 <p><span id="es6-module-exports"></span></p>
340 <h4 id="es-module-exports">3.4.2 Exports</h4>
343 Non-exported module-local symbols are not declared <code>@private</code> nor do their names
345 module-local symbols.</p>
347 <h5 id="named-vs-default-exports">3.4.2.1 Named vs default exports</h5>
355 <pre><code class="language-js badcode prettyprint">// Do not use default exports:
359 <pre><code class="language-js good prettyprint">// Use named exports:
363 <pre><code class="language-js good prettyprint">// Alternate style named exports:
369 <h5 id="exporting-static-containers">3.4.2.2 Exporting static container classes and objects</h5>
374 <pre><code class="language-js badcode prettyprint">// container.js
389 <pre><code class="language-js good prettyprint">/** @return {number} */
397 <p><span id="es6-exports-mutability"></span></p>
399 <h5 id="esm-exports-mutability">3.4.2.3 Mutability of exports</h5>
407 <pre><code class="language-js badcode prettyprint">// Bad: both foo and mutateFoo are exported and …
428 <pre><code class="language-js good prettyprint">// Good: Rather than export the mutable variables f…
449 <p><span id="es6-module-circular-dependencies"></span></p>
451 <h5 id="es-module-export-from">3.4.2.4 export from</h5>
454 exception to the 80-column limit. This applies to both <code>export from</code> flavors.</p>
456 <pre><code class="language-js">export {specificName} from './other.js';
460 <h4 id="es-module-circular-dependencies">3.4.3 Circular Dependencies in ES modules</h4>
466 <pre><code class="language-js badcode prettyprint">// a.js
470 <pre><code class="language-js badcode prettyprint">// b.js
477 <pre><code class="language-js badcode prettyprint">// c.js
483 <p><span id="es6-module-closure-interop"></span></p>
485 <h4 id="es-module-closure-interop">3.4.4 Interoperating with Closure</h4>
487 <p><span id="es6-module-referencing-goog"></span></p>
489 <h5 id="es-module-referencing-goog">3.4.4.1 Referencing goog</h5>
493 <pre><code class="language-js good prettyprint external">import * as goog from '../closure/goog/goo…
503 <p><span id="goog-require-in-es6-module"></span></p>
505 <h5 id="goog-require-in-es-module">3.4.4.2 goog.require in ES modules</h5>
511 <pre><code class="language-js prettyprint external">import * as goog from '../closure/goog/goog.js';
518 <p><span id="closure-module-id-in-es6-module"></span></p>
520 <h5 id="closure-module-id-in-es-module">3.4.4.3 Declaring Closure Module IDs in ES modules</h5>
523 <code>goog.module</code>-like module ID. This means that this module ID can be
540 <pre><code class="language-js prettyprint external">import * as goog from '../closure/goog.js';
547 <h3 id="file-set-test-only">3.5 <code>goog.setTestOnly</code></h3>
555 <h3 id="file-goog-require">3.6 <code>goog.require</code> and <code>goog.requireType</code> statemen…
564 <a href="#source-file-structure">by a single empty line</a>. The entire argument to
578 <p>Aliases must match the final dot-separated component of the imported module's
587 …ozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects">Standard Built-in Objects</a> and <…
589 as required in <a href="#formatting-horizontal-whitespace">??</a>.</p>
612 <p>If a long alias or module name would cause a line to exceed the 80-column limit,
613 it <strong>must not</strong> be wrapped: require lines are an exception to the 80-column
618 <pre><code class="language-js prettyprint">// Standard alias style.
621 // Namespace-based alias used to disambiguate.
623 // Namespace-based alias used to prevent masking native type.
625 // Out of sequence namespace-based aliases used to improve readability.
631 // Namespace-based alias used to disambiguate.
636 // Namespace-based destructuring into aliases in order to disambiguate.
646 <pre><code class="language-js badcode prettyprint">// If necessary to disambiguate, prefer PackageC…
653 <pre><code class="language-js badcode prettyprint">// Extra terms must come from the namespace.
681 <h3 id="file-implementation">3.7 The file’s implementation</h3>
686 <p>This may consist of any module-local declarations (constants, variables,
692 <p><strong>Terminology Note</strong>: <em>block-like construct</em> refers to the body of a class,
693 function, method, or brace-delimited block of code. Note that, by
694 <a href="#features-array-literals">??</a> and <a href="#features-object-literals">??</a>, any array…
695 object literal may optionally be treated as if it were a block-like construct.</p>
697 <p>Tip: Use <code>clang-format</code>. The JavaScript community has invested effort to make
698 sure clang-format <q>does the right thing</q> on JavaScript files. <code>clang-format</code> has
702 <h3 id="formatting-braces">4.1 Braces</h3>
704 <h4 id="formatting-braces-all">4.1.1 Braces are used for all control structures</h4>
708 statement. The first statement of a non-empty block must begin on its own line.</p>
712 <pre><code class="language-js badcode prettyprint">if (someVeryLongCondition())
723 <pre><code class="language-js prettyprint">if (shortCondition()) foo();
726 <h4 id="formatting-nonempty-blocks">4.1.2 Nonempty blocks: K&R style</h4>
728 …itchie style (<q><a href="http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html">Eg…
729 <em>nonempty</em> blocks and block-like constructs:</p>
738 <code>while</code>, or a comma, semicolon, or right-parenthesis.</li>
743 <pre><code class="language-js prettyprint">class InnerClass {
760 <h4 id="formatting-empty-blocks">4.1.3 Empty blocks: may be concise</h4>
762 <p>An empty block or block-like construct <em>may</em> be closed immediately after it is
764 <strong>unless</strong> it is a part of a <em>multi-block statement</em> (one that directly contains
769 <pre><code class="language-js prettyprint">function doNothing() {}
774 <pre><code class="language-js prettyprint badcode">if (condition) {
785 <h3 id="formatting-block-indentation">4.2 Block indentation: +2 spaces</h3>
787 <p>Each time a new block or block-like construct is opened, the indent increases by
790 block. (See the example in <a href="#formatting-nonempty-blocks">??</a>).</p>
792 <h4 id="formatting-array-literals">4.2.1 Array literals: optionally <q>block-like</q></h4>
794 <p>Any array literal may optionally be formatted as if it were a “block-like
798 <pre><code class="language-js prettyprint columns">const a = [
809 <pre><code class="language-js prettyprint columns">const c = [0, 1, 2];
820 <h4 id="formatting-object-literals">4.2.2 Object literals: optionally <q>block-like</q></h4>
822 <p>Any object literal may optionally be formatted as if it were a “block-like
823 construct.” The same examples apply as <a href="#formatting-array-literals">??</a>. For
826 <pre><code class="language-js prettyprint columns">const a = {
835 <pre><code class="language-js prettyprint columns">const c = {a: 0, b: 1};
842 <h4 id="formatting-class-literals">4.2.3 Class literals</h4>
852 <pre><code class="language-js prettyprint columns">class Foo {
866 <pre><code class="language-js prettyprint columns">/** @extends {Foo<string>} */
881 <h4 id="formatting-function-expressions">4.2.4 Function expressions</h4>
889 <pre><code class="language-js prettyprint">prefix.something.reallyLongFunctionName('whatever', (a1,…
910 <h4 id="formatting-switch-statements">4.2.5 Switch statements</h4>
925 <pre><code class="language-js prettyprint">switch (animal) {
939 <h3 id="formatting-statements">4.3 Statements</h3>
941 <h4 id="formatting-one-statement-perline">4.3.1 One statement per line</h4>
943 <p>Each statement is followed by a line-break.</p>
945 <h4 id="formatting-semicolons-are-required">4.3.2 Semicolons are required</h4>
950 <h3 id="formatting-column-limit">4.4 Column limit: 80</h3>
953 line that would exceed this limit must be line-wrapped, as explained in
954 <a href="#formatting-line-wrapping">??</a>.</p>
960 <a href="#file-goog-module">??</a> and <a href="#file-goog-require">??</a>).</li>
962 <a href="#es-module-imports">??</a> and <a href="#es-module-export-from">??</a>).</li>
967 <li>A shell command intended to be copied-and-pasted.</li>
973 <h3 id="formatting-line-wrapping">4.5 Line-wrapping</h3>
980 line-wrap in every situation. Very often there are several valid ways to
981 line-wrap the same piece of code.</p>
983 <p>Note: While the typical reason for line-wrapping is to avoid overflowing the
985 line-wrapped at the author's discretion.</p>
988 need to line-wrap.</p>
990 <h4 id="formatting-where-to-break">4.5.1 Where to break</h4>
992 <p>The prime directive of line-wrapping is: prefer to break at a <strong>higher syntactic
997 <pre><code class="language-js prettyprint">currentEstimate =
1004 <pre><code class="language-js prettyprint badcode">currentEstimate = calc(currentEstimate + x *
1030 <h4 id="formatting-indent">4.5.2 Indent continuation lines at least +4 spaces</h4>
1032 <p>When line-wrapping, each line after the first (each <em>continuation line</em>) is
1041 <p><a href="#formatting-horizontal-alignment">??</a> addresses the discouraged practice of
1044 <h3 id="formatting-whitespace">4.6 Whitespace</h3>
1046 <h4 id="formatting-vertical-whitespace">4.6.1 Vertical whitespace</h4>
1062 <a href="#file-goog-require">??</a>).</li>
1068 <h4 id="formatting-horizontal-whitespace">4.6.2 Horizontal whitespace</h4>
1096 <li>On both sides of the double slash (<code>//</code>) that begins an end-of-line comment.
1098 <li>After an open-block comment character and on both sides of close characters
1099 (e.g. for short-form type declarations, casts, and parameter name comments:
1104 <h4 id="formatting-horizontal-alignment">4.6.3 Horizontal alignment: discouraged</h4>
1117 <pre><code class="language-js prettyprint">{
1130 change may leave the formerly-pleasing formatting mangled, and that is
1133 reformattings. That one-line change now has a <q>blast radius.</q> This can at worst
1137 <h4 id="formatting-function-arguments">4.6.4 Function arguments</h4>
1139 …e as the function name. If doing so would exceed the 80-column limit, the arguments must be line-w…
1141 <pre><code class="language-js prettyprint">// Arguments start on a new line, indented four spaces. …
1157 // Four-space, one argument per line. Works with long function names,
1168 <h3 id="formatting-grouping-parentheses">4.7 Grouping parentheses: recommended</h3>
1181 <h3 id="formatting-comments">4.8 Comments</h3>
1186 <h4 id="formatting-block-comment-style">4.8.1 Block comment style</h4>
1189 be in <code>/* … */</code> or <code>//</code>-style. For multi-line <code>/* … */</code…
1193 <pre><code class="language-js prettyprint">/*
1208 <h4 id="formatting-param-name-comments">4.8.2 Parameter Name Comments</h4>
1215 <pre><code class="language-js prettyprint">someFunction(obviousParam, /* shouldRender= */ true, /* …
1221 <pre><code class="language-js prettyprint">someFunction(obviousParam, true /* shouldRender */, 'hel…
1224 <h2 id="language-features">5 Language features</h2>
1230 <h3 id="features-local-variable-declarations">5.1 Local variable declarations</h3>
1232 <h4 id="features-use-const-and-let">5.1.1 Use <code>const</code> and <code>let</code></h4>
1238 <h4 id="features-one-variable-per-declaration">5.1.2 One variable per declaration</h4>
1243 <h4 id="features-declared-when-needed">5.1.3 Declared when needed, initialized as soon as possible<…
1246 block or block-like construct. Instead, local variables are declared close to
1249 <h4 id="features-declare-types-as-needed">5.1.4 Declare types as needed</h4>
1256 <pre><code class="language-js prettyprint">const /** !Array<number> */ data = [];
1268 <pre><code class="language-js prettyprint badcode">/** Some description. */
1279 <h3 id="features-array-literals">5.2 Array literals</h3>
1281 <h4 id="features-arrays-trailing-comma">5.2.1 Use trailing commas</h4>
1290 <pre><code class="language-js prettyprint">const values = [
1296 <h4 id="features-arrays-ctor">5.2.2 Do not use the variadic <code>Array</code> constructor</h4>
1298 <p>The constructor is error-prone if arguments are added or removed. Use a literal
1303 <pre><code class="language-js prettyprint badcode">const a1 = new Array(x1, x2, x3);
1312 it will be a single-element array.</p>
1316 <pre><code class="language-js prettyprint">const a1 = [x1, x2, x3];
1325 <h4 id="features-arrays-non-numeric-properties">5.2.3 Non-numeric properties</h4>
1327 <p>Do not define or use non-numeric properties on an array (other than
1330 <h4 id="features-arrays-destructuring">5.2.4 Destructuring</h4>
1332 <p>Array literals may be used on the left-hand side of an assignment to perform
1337 <pre><code class="language-js prettyprint">const [a, b, c, ...rest] = generateResults();
1346 <pre><code class="language-js prettyprint">/** @param {!Array<number>=} param1 */
1352 <pre><code class="language-js prettyprint badcode">function badDestructuring([a, b] = [4, 2]) { …
1359 <h4 id="features-arrays-spread-operator">5.2.5 Spread operator</h4>
1368 <pre><code class="language-js prettyprint">[...foo] // preferred over Array.prototype.slice.call(…
1372 <h3 id="features-object-literals">5.3 Object literals</h3>
1374 <h4 id="features-objects-use-trailing-comma">5.3.1 Use trailing commas</h4>
1379 <h4 id="features-objects-ctor">5.3.2 Do not use the <code>Object</code> constructor</h4>
1385 <h4 id="features-objects-mixing-keys">5.3.3 Do not mix quoted and unquoted keys</h4>
1393 <pre><code class="language-js prettyprint badcode">{
1394 width: 42, // struct-style unquoted key
1395 'maxWidth': 43, // dict-style quoted key
1405 <pre><code class="language-js prettyprint badcode">/** @type {{width: number, maxWidth: (number|und…
1414 <pre><code class="language-js prettyprint">/** @type {{width: number, maxWidth: (number|undefined)}…
1421 <h4 id="features-objects-computed-property-names">5.3.4 Computed property names</h4>
1424 considered dict-style (quoted) keys (i.e., must not be mixed with non-quoted
1426 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol">s…
1428 should not be mixed with non-enum keys in the same literal.</p>
1430 <h4 id="features-objects-method-shorthand">5.3.5 Method shorthand</h4>
1438 <pre><code class="language-js prettyprint">return {
1452 <pre><code class="language-js prettyprint">class {
1463 <h4 id="features-objects-shorthand-properties">5.3.6 Shorthand properties</h4>
1469 <pre><code class="language-js prettyprint">const foo = 1;
1479 <h4 id="features-objects-destructuring">5.3.7 Destructuring</h4>
1481 <p>Object destructuring patterns may be used on the left-hand side of an assignment
1487 destructuring. Specify any default values in the left-hand-side of the
1495 <pre><code class="language-js prettyprint">/**
1506 <pre><code class="language-js prettyprint badcode">/** @param {{x: {num: (number|undefined), str: (…
1518 long it is (see <a href="#file-goog-require">??</a>).</p>
1520 <h4 id="features-objects-enums">5.3.8 Enums</h4>
1526 <pre><code class="language-js prettyprint">/**
1547 <h3 id="features-classes">5.4 Classes</h3>
1549 <h4 id="features-classes-constructors">5.4.1 Constructors</h4>
1553 non-method properties in the constructor.</p>
1555 <h4 id="features-classes-fields">5.4.2 Fields</h4>
1559 (these need not be deeply immutable). Annotate non-public fields with the proper
1566 <pre><code class="language-js prettyprint">class Foo {
1584 <h4 id="features-classes-computed-properties">5.4.3 Computed properties</h4>
1589 symbol. Dict-style properties (that is, quoted or computed non-symbol keys, as
1590 defined in <a href="#features-objects-mixing-keys">??</a>) are not allowed. A
1594 <p>Tip: be careful of using any other built-in symbols (e.g., <code>Symbol.isConcatSpreadable</code…
1596 <h4 id="features-classes-static-methods">5.4.4 Static methods</h4>
1600 <p>Where it does not interfere with readability, prefer module-local functions over
1611 <pre><code class="language-js prettyprint badcode">class Base { /** @nocollapse */ static foo() {} }
1617 <h4 id="features-classes-old-style">5.4.5 Old-style class declarations</h4>
1636 <p><code>goog.defineClass</code> allows for a class-like definition similar to ES6 class
1639 <pre><code class="language-javascript">let C = goog.defineClass(S, {
1662 <pre><code class="language-javascript">/**
1682 <p>Per-instance properties should be defined in the constructor after the call to the super class c…
1686 <h4 id="features-classes-prototypes">5.4.6 Do not manipulate <code>prototype</code>s directly</h4>
1691 defined in <a href="#features-classes-old-style">??</a>. Mixins and modifying the
1695 resort to even-worse workarounds to avoid doing so.</p>
1697 <h4 id="features-classes-getters-and-setters">5.4.7 Getters and Setters</h4>
1699 <p>Do not use <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/…
1713 <pre><code class="language-js prettyprint badcode">class Foo {
1718 <h4 id="features-classes-overriding-tostring">5.4.8 Overriding toString</h4>
1726 <h4 id="features-classes-interfaces">5.4.9 Interfaces</h4>
1732 <p>All non-static method bodies on an interface must be empty blocks. Fields must
1737 <pre><code class="language-js prettyprint">/**
1756 <h4 id="features-classes-abstract-classes">5.4.10 Abstract Classes</h4>
1759 …hod</code>. See <a href="https://github.com/google/closure-compiler/wiki/@abstract-classes-and-met…
1762 <h3 id="features-functions">5.5 Functions</h3>
1764 <h4 id="features-functions-top-level-functions">5.5.1 Top-level functions</h4>
1766 <p>Top-level functions may be defined directly on the <code>exports</code> object, or else
1767 declared locally and optionally exported. See <a href="#file-goog-module-exports">??</a>
1772 <pre><code class="language-js prettyprint">/** @param {string} str */
1778 <pre><code class="language-js prettyprint">/** @param {string} str */
1786 <h4 id="features-functions-nested-functions">5.5.2 Nested functions and closures</h4>
1791 <h4 id="features-functions-arrow-functions">5.5.3 Arrow functions</h4>
1796 <a href="#features-objects-method-shorthand">??</a>).</p>
1804 <p>The left-hand side of the arrow contains zero or more parameters. Parentheses
1805 around the parameters are optional if there is only a single non-destructured
1807 (see <a href="#jsdoc-method-and-function-comments">??</a>).</p>
1809 <p>Tip: Always using parentheses even for single-parameter arrow functions can
1813 <p>The right-hand side of the arrow contains the body of the function. By default
1824 <pre><code class="language-js prettyprint">/**
1853 <pre><code class="language-js prettyprint badcode">/**
1861 <h4 id="features-functions-generators">5.5.4 Generators</h4>
1871 <pre><code class="language-js prettyprint">/** @return {!Iterator<number>} */
1889 <h4 id="features-functions-parameter-return-types">5.5.5 Parameter and return types</h4>
1892 annotations. See <a href="#jsdoc-method-and-function-comments">??</a> for more information.</p>
1894 <h5 id="features-functions-default-parameters">5.5.5.1 Default parameters</h5>
1907 <pre><code class="language-js prettyprint">/**
1925 <a href="#features-objects-destructuring">??</a>) to create readable APIs when there
1939 <h5 id="features-functions-rest-parameters">5.5.5.2 Rest parameters</h5>
1945 parameter <code>arguments</code>, which confusingly shadows the built-in name.</p>
1949 <pre><code class="language-js prettyprint">/**
1956 <h4 id="features-functions-generics">5.5.6 Generics</h4>
1961 <h4 id="features-functions-spread-operator">5.5.7 Spread operator</h4>
1969 <pre><code class="language-js prettyprint">function myFunction(...elements) {}
1973 <h3 id="features-string-literals">5.6 String literals</h3>
1975 <h4 id="features-strings-use-single-quotes">5.6.1 Use single quotes</h4>
1985 <h4 id="features-strings-template-strings">5.6.2 Template literals</h4>
1997 <pre><code class="language-js prettyprint">function arithmetic(a, b) {
2000 ${a} - ${b} = ${a - b}
2006 <h4 id="features-strings-no-line-continuations">5.6.3 No line continuations</h4>
2015 <pre><code class="language-js prettyprint badcode">const longString = 'This is a very long string t…
2022 <pre><code class="language-js prettyprint">const longString = 'This is a very long string that far …
2027 <h3 id="features-number-literals">5.7 Number literals</h3>
2034 <h3 id="features-control-structures">5.8 Control structures</h3>
2036 <h4 id="features-for-loops">5.8.1 For loops</h4>
2039 used, though <code>for</code>-<code>of</code> loops should be preferred when possible.</p>
2041 <p><code>for</code>-<code>in</code> loops may only be used on dict-style objects (see
2042 <a href="#features-objects-mixing-keys">??</a>), and should not be used to iterate over an
2043 array. <code>Object.prototype.hasOwnProperty</code> should be used in <code>for</code>-<code>in</c…
2044 exclude unwanted prototype properties. Prefer <code>for</code>-<code>of</code> and <code>Object.ke…
2045 <code>for</code>-<code>in</code> when possible.</p>
2047 <h4 id="features-exceptions">5.8.2 Exceptions</h4>
2061 <p>Prefer throwing exceptions over ad-hoc error-handling approaches (such as
2065 <h5 id="features-empty-catch-blocks">5.8.2.1 Empty catch blocks</h5>
2071 <pre><code class="language-js prettyprint">try {
2081 <pre><code class="language-js prettyprint badcode"> try {
2091 <h4 id="features-switch-statements">5.8.3 Switch statements</h4>
2093 …re statement groups. Each statement group consists of one or more switch labels (either <code>case…
2095 <h5 id="features-switch-fall-through">5.8.3.1 Fall-through: commented</h5>
2100 group. Any comment that communicates the idea of fall-through is sufficient
2106 <pre><code class="language-js prettyprint">switch (input) {
2119 <h5 id="features-switch-default-case">5.8.3.2 The <code>default</code> case is present</h5>
2124 <h3 id="features-this">5.9 this</h3>
2128 <code>@this</code> declared in the immediately-enclosing function’s JSDoc.</p>
2133 <h3 id="features-equality-checks">5.10 Equality Checks</h3>
2137 <h4 id="features-equality-checks-exceptions">5.10.1 Exceptions Where Coercion is Desirable</h4>
2141 <pre><code class="language-js prettyprint">if (someObjectOrPrimitive == null) {
2148 <h3 id="disallowed-features">5.11 Disallowed features</h3>
2150 <h4 id="disallowed-features-with">5.11.1 with</h4>
2155 <h4 id="disallowed-features-dynamic-code-evaluation">5.11.2 Dynamic code evaluation</h4>
2161 <h4 id="disallowed-features-automatic-semicolon-insertion">5.11.3 Automatic semicolon insertion</h4>
2166 <h4 id="disallowed-features-non-standard-features">5.11.4 Non-standard features</h4>
2168 <p>Do not use non-standard features. This includes old features that have been
2171 not-yet-complete web standards), or proprietary features that are only
2172 implemented in some browsers. Use only features defined in the current ECMA-262
2174 Chrome extensions or Node.js, can obviously use those APIs). Non-standard
2178 <h4 id="disallowed-features-wrapper-objects">5.11.5 Wrapper objects for primitive types</h4>
2185 <pre><code class="language-js prettyprint badcode">const /** Boolean */ x = new Boolean(false);
2186 if (x) alert(typeof x); // alerts 'object' - WAT?
2194 <pre><code class="language-js prettyprint">const /** boolean */ x = Boolean(0);
2198 <h4 id="disallowed-features-modifying-builtin-objects">5.11.6 Modifying builtin objects</h4>
2202 JSCompiler’s runtime library will provide standards-compliant polyfills where
2206 (e.g. required by a third-party API).</p>
2208 <h4 id="disallowed-features-omitting-parents-with-new">5.11.7 Omitting <code>()</code> when invokin…
2214 <pre><code class="language-js prettyprint badcode">new Foo;
2219 <pre><code class="language-js prettyprint">new Foo();
2225 <pre><code class="language-js prettyprint">new Foo().Bar();
2231 <h3 id="naming-rules-common-to-all-identifiers">6.1 Rules common to all identifiers</h3>
2243 <pre><code class="language-js prettyprint">errorCount // No abbreviation.
2251 <pre><code class="language-js prettyprint badcode">n // Meaningless.
2260 <h3 id="naming-rules-by-identifier-type">6.2 Rules by identifier type</h3>
2262 <h4 id="naming-package-names">6.2.1 Package names</h4>
2267 <h4 id="naming-class-names">6.2.2 Class names</h4>
2277 <h4 id="naming-method-names">6.2.3 Method names</h4>
2292 <h4 id="naming-enum-names">6.2.4 Enum names</h4>
2298 <h4 id="naming-constant-names">6.2.5 Constant names</h4>
2305 <h5 id="naming-definition-of-constant">6.2.5.1 Definition of “constant”</h5>
2307 <p>Every constant is a <code>@const</code> static property or a module-local <code>const</code>
2308 declaration, but not all <code>@const</code> static properties and module-local <code>const</code>s
2316 <pre><code class="language-js prettyprint">// Constants
2322 let letVariable = 'non-const';
2323 class MyClass { constructor() { /** @const {string} */ this.nonStatic = 'non-static'; } };
2333 <h5 id="naming-local-aliases">6.2.5.2 Local aliases</h5>
2336 fully-qualified names. Follow the same rules as <code>goog.require</code>s
2337 (<a href="#file-goog-require">??</a>), maintaining the last part of the aliased name.
2342 <pre><code class="language-js prettyprint">const staticHelper = importedNamespace.staticHelper;
2347 <h4 id="naming-non-constant-field-names">6.2.6 Non-constant field names</h4>
2349 <p>Non-constant field names (static or otherwise) are written in <code>lowerCamelCase</code>,
2355 <h4 id="naming-parameter-names">6.2.7 Parameter names</h4>
2360 <p>One-character parameter names should not be used in public methods.</p>
2362 <p><strong>Exception</strong>: When required by a third-party framework, parameter names may
2366 <h4 id="naming-local-variable-names">6.2.8 Local variable names</h4>
2368 <p>Local variable names are written in <code>lowerCamelCase</code>, except for module-local
2369 (top-level) constants, as described above. Constants in function scopes are
2373 <h4 id="naming-template-parameter-names">6.2.9 Template parameter names</h4>
2375 <p>Template parameter names should be concise, single-word or single-letter
2376 identifiers, and must be all-caps, such as <code>TYPE</code> or <code>THIS</code>.</p>
2378 <h4 id="naming-module-local-names">6.2.10 Module-local names</h4>
2380 <p>Module-local names that are not exported are implicitly private. They are not
2382 functions, variables, constants, enums, and other module-local identifiers.</p>
2384 <h3 id="naming-camel-case-defined">6.3 Camel case: defined</h3>
2421 <th style="text-align: center">Prose form</th>
2422 <th style="text-align: center">Correct</th>
2423 <th style="text-align: center">Incorrect</th>
2429 <td style="text-align: center"><q>XML HTTP request</q></td>
2430 <td style="text-align: center">XmlHttpRequest</td>
2431 <td style="text-align: center">XMLHTTPRequest</td>
2434 <td style="text-align: center"><q>new customer ID</q></td>
2435 <td style="text-align: center">newCustomerId</td>
2436 <td style="text-align: center">newCustomerID</td>
2439 <td style="text-align: center"><q>inner stopwatch</q></td>
2440 <td style="text-align: center">innerStopwatch</td>
2441 <td style="text-align: center">innerStopWatch</td>
2444 <td style="text-align: center"><q>supports IPv6 on iOS?</q></td>
2445 <td style="text-align: center">supportsIpv6OnIos</td>
2446 <td style="text-align: center">supportsIPv6OnIOS</td>
2449 <td style="text-align: center"><q>YouTube importer</q></td>
2450 <td style="text-align: center">YouTubeImporter</td>
2451 <td style="text-align: center">YoutubeImporter*</td>
2458 …y hyphenated in the English language: for example <q>nonempty</q> and <q>non-empty</q> are both co…
2462 <p><a href="https://developers.google.com/closure/compiler/docs/js-for-compiler">JSDoc</a> is used …
2464 <h3 id="jsdoc-general-form">7.1 General form</h3>
2468 <pre><code class="language-js prettyprint">/**
2476 <p>or in this single-line example:</p>
2478 <pre><code class="language-js prettyprint">/** @const @private {!Foo} A short bit of JSDoc. */
2482 <p>If a single-line comment overflows into multiple lines, it must use the
2483 multi-line style with <code>/**</code> and <code>*/</code> on their own lines.</p>
2486 optimization. As such, these comments <strong>must</strong> be well-formed.</p>
2488 <h3 id="jsdoc-markdown">7.2 Markdown</h3>
2492 <p>Note that tools that automatically extract JSDoc (e.g. <a href="https://github.com/jleyba/js-dos…
2495 <pre><code class="language-js prettyprint badcode">/**
2510 <pre><code class="language-js prettyprint">/**
2513 * - items sent
2514 * - items received
2515 * - last timestamp
2519 <h3 id="jsdoc-tags">7.3 JSDoc tags</h3>
2522 <a href="#appendices-jsdoc-tag-reference">??</a> for the complete list. Most tags must
2527 <pre><code class="language-js prettyprint badcode">/**
2538 <pre><code class="language-js prettyprint">/**
2562 …-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler">Annotating JavaScript for the Closu…
2565 <h3 id="jsdoc-line-wrapping">7.4 Line wrapping</h3>
2567 <p>Line-wrapped block tags are indented four spaces. Wrapped description text may
2571 <pre><code class="language-js prettyprint">/**
2585 <h3 id="jsdoc-top-file-level-comments">7.5 Top/file-level comments</h3>
2587 <p>A file may have a top-level file overview. A copyright notice , author information, and
2588 default <a href="#jsdoc-visibility-annotations">visibility level</a> are optional. File overviews …
2596 <pre><code class="language-js prettyprint">/**
2603 <h3 id="jsdoc-class-comments">7.6 Class comments</h3>
2614 <pre><code class="language-js prettyprint">/**
2640 <h3 id="jsdoc-enum-and-typedef-comments">7.7 Enum and typedef comments</h3>
2647 <pre><code class="language-js prettyprint">/**
2661 /** The less-frumious kind. */
2673 <h3 id="jsdoc-method-and-function-comments">7.8 Method and function comments</h3>
2676 except in the case of same-signature <code>@override</code>s, where all types are omitted.
2678 if the function has no non-empty <code>return</code> statements.</p>
2693 <pre><code class="language-js prettyprint">/** A class that does something. */
2709 * Demonstrates how top-level functions follow the same rules. This one
2722 <pre><code class="language-js prettyprint">function /** string */ foo(/** number */ arg) {...}
2728 <pre><code class="language-js prettyprint">class MyClass {
2737 <pre><code class="language-js prettyprint badcode">// Illegal inline JSDocs.
2752 <pre><code class="language-js prettyprint">promise.then(
2760 <p>For function type expressions, see <a href="#jsdoc-function-types">??</a>.</p>
2762 <h3 id="jsdoc-property-comments">7.9 Property comments</h3>
2770 <pre><code class="language-js prettyprint">/** My class. */
2795 <h3 id="jsdoc-type-annotations">7.10 Type annotations</h3>
2801 <h4 id="jsdoc-nullability">7.10.1 Nullability</h4>
2803 <p>The type system defines modifiers <code>!</code> and <code>?</code> for non-null and nullable,
2812 string...}}</code>) are always non-nullable by default. Use the <code>?</code> modifier to
2824 <pre><code class="language-js prettyprint badcode">const /** MyObject */ myObject = null; // Non-pr…
2825 const /** !number */ someNum = 5; // Primitives are non-nullable by default.
2827 const /** !{foo: string, bar: number} */ record = ...; // Already non-nullable.
2830 // Not sure if object (nullable), enum (non-nullable, unless otherwise
2837 <pre><code class="language-js prettyprint">const /** ?MyObject */ myObject = null;
2845 <h4 id="jsdoc-type-casts">7.10.2 Type Casts</h4>
2849 <a href="https://google.github.io/closure-library/api/goog.asserts.html">goog.asserts</a>
2854 <pre><code class="language-js prettyprint">/** @type {number} */ (x)
2857 <h4 id="jsdoc-template-parameter-types">7.10.3 Template Parameter Types</h4>
2864 <pre><code class="language-js prettyprint badcode">const /** !Object */ users = {};
2871 <pre><code class="language-js prettyprint">const /** !Object<string, !User> */ users = {};
2882 <li><code>Object</code> is used for type hierarchy and not as map-like structure.</li>
2885 <h4 id="jsdoc-function-types">7.10.4 Function type expressions</h4>
2893 annotations (see <a href="#jsdoc-method-and-function-comments">??</a>). This includes
2901 <pre><code class="language-js prettyprint"> /** @private {function(string): string} */
2909 <p>Bad - type error, but no warning given:</p>
2911 <pre><code class="language-js prettyprint badcode">/** @param {function()} generateNumber */
2913 const /** number */ x = generateNumber(); // No compile-time type error here.
2921 <pre><code class="language-js prettyprint">/**
2930 <h4 id="jsdoc-whitespace">7.10.5 Whitespace</h4>
2935 following the applicable guidelines (e.g. <a href="#formatting-line-wrapping">??</a> and
2936 <a href="#formatting-block-indentation">??</a>). No other whitespace is allowed in type
2941 <pre><code class="language-js prettyprint">/** @type {function(string): number} */
2965 <pre><code class="language-js prettyprint badcode">// Only put a space after the colon
2975 <h3 id="jsdoc-visibility-annotations">7.11 Visibility annotations</h3>
2984 <h3 id="policies-be-consistent">8.1 Issues unspecified by Google Style: Be Consistent!</h3>
2991 <h3 id="policies-compiler-warnings">8.2 Compiler warnings</h3>
2993 <h4 id="policies-use-a-standard-warning-set">8.2.1 Use a standard warning set</h4>
2996 As far as possible projects should use <code>--warning_level=VERBOSE</code>.
2999 <h4 id="policies-how-to-handle-a-warning">8.2.2 How to handle a warning</h4>
3020 <h4 id="policies-suppress-a-warning-at-the-narrowest-reasonable-scope">8.2.3 Suppress a warning at …
3026 <pre><code class="language-js prettyprint">/** @suppress {uselessCode} Unrecognized 'use asm' decla…
3036 <h3 id="policies-deprecation">8.3 Deprecation</h3>
3042 <h3 id="policies-code-not-in-google-style">8.4 Code not in Google Style</h3>
3046 before Google Style took a position on some issue, or may be in non-Google Style
3049 <h4 id="policies-reformatting-existing-code">8.4.1 Reformatting existing code</h4>
3055 guidelines. Reformatting existing code is a trade-off between code churn
3065 <h4 id="policies-newly-added-code-use-google-style">8.4.2 Newly added code: use Google Style</h4>
3072 <a href="#policies-reformatting-existing-code">??</a>.</p>
3078 <h3 id="policies-local-style-rules">8.5 Local style rules</h3>
3086 <h3 id="policies-generated-code-mostly-exempt">8.6 Generated code: mostly exempt</h3>
3090 hand-written source code must follow the naming requirements. As a special
3092 to avoid conflicts with hand-written identifiers.</p>
3096 <h3 id="appendices-jsdoc-tag-reference">9.1 JSDoc tag reference</h3>
3102 <h4 id="appendices-type-annotations">9.1.1 Type annotations and other Closure Compiler annotations<…
3105 …-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler">Annotating JavaScript for the Closu…
3108 <h4 id="appendices-documentation-annotations">9.1.2 Documentation annotations</h4>
3110 …ibed in <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Clo…
3112 documentation generation tools (such as <a href="https://github.com/jleyba/js-dossier">JsDossier</a…
3115 <p>You may also see other types of JSDoc annotations in third-party code. These
3116 annotations appear in the <a href="http://code.google.com/p/jsdoc-toolkit/wiki/TagReference">JSDoc …
3121 <h5>9.1.2.1 <code>@author</code> or <code>@owner</code> - <em>Not recommended.</em></h5>
3127 <pre><code class="language-js prettyprint">/**
3145 <pre><code class="language-js prettyprint">/** @bug 1234567 */
3168 <h5>9.1.2.3 <code>@code</code> - <em>Deprecated. Do not use.</em></h5>
3177 <pre><code class="language-js prettyprint">/** Processes pending `BatchItem` instances. */
3192 <pre><code class="language-js prettyprint">/** @desc Notifying a user that their account has been c…
3205 <p>This tag is used to generate cross-reference links within generated
3208 <pre><code class="language-js prettyprint">/** Processes pending {@link BatchItem} instances. */
3216 <pre><code class="language-js prettyprint">/**
3231 <pre><code class="language-js prettyprint">/**
3249 <pre><code class="language-js prettyprint">/**
3260 <h4 id="appendices-framework-specific-annotations">9.1.3 Framework specific annotations</h4>
3276 …"https://github.com/google/closure-compiler/wiki/Polymer-Pass">https://github.com/google/closure-c…
3285 <h4 id="appendices-notes-about-standard-closure-compiler-annotations">9.1.4 Notes about standard Cl…
3291 <h5>9.1.4.1 <code>@expose</code> - <em>Deprecated. Do not use.</em></h5>
3299 <h5>9.1.4.2 <code>@inheritDoc</code> - <em>Deprecated. Do not use.</em></h5>
3329 <h3 id="appendices-commonly-misunderstood-style-rules">9.2 Commonly misunderstood style rules</h3>
3331 <p>Here is a collection of lesser-known or commonly misunderstood facts about
3339 class (<a href="#features-classes">??</a>).</li>
3341 (<a href="#formatting-empty-blocks">??</a>).</li>
3342 <li>The prime directive of line-wrapping is: prefer to break at a higher
3343 syntactic level (<a href="#formatting-where-to-break">??</a>).</li>
3344 <li>Non-ASCII characters are allowed in string literals, comments and JSDoc,
3346 equivalent Unicode escape would (<a href="#non-ascii-characters">??</a>).</li>
3349 <h3 id="appendices-style-related-tools">9.3 Style-related tools</h3>
3353 <h4 id="appendices-tools-closure-compiler">9.3.1 Closure Compiler</h4>
3359 <h4 id="appendices-clang-format">9.3.2 <code>clang-format</code></h4>
3363 non-required but frequently readability-enhancing formatting practices.
3364 The output produced by <code>clang-format</code> is compliant with the style guide.
3367 <p><code>clang-format</code> is not required. Authors are allowed to change its output, and
3371 <h4 id="appendices-closure-compiler-linter">9.3.3 Closure compiler linter</h4>
3374 variety of missteps and anti-patterns.
3377 <h4 id="appendices-conformance-framework">9.3.4 Conformance framework</h4>
3390 <a href="https://github.com/google/closure-compiler/wiki/JS-Conformance-Framework">JS Conformance F…
3392 <h3 id="appendices-legacy-exceptions">9.4 Exceptions for legacy platforms</h3>
3394 <h4 id="appendices-legacy-exceptions-overview">9.4.1 Overview</h4>
3407 <h4 id="appendices-legacy-exceptions-var">9.4.2 Use <code>var</code></h4>
3409 <h5 id="appendices-legacy-exceptions-var-scope">9.4.2.1 <code>var</code> declarations are NOT block…
3416 <pre><code class="language-js prettyprint badcode">for (var i = 0; i < 3; ++i) {
3421 // logs 2, 2, 2 -- NOT 0, 1, 2
3422 // because `iteration` is function-scoped, not local to the loop.
3426 <h5 id="appendices-legacy-exceptions-var-declare">9.4.2.2 Declare variables as close as possible to…
3433 <pre><code class="language-js prettyprint">function sillyFunction() {
3443 <h5 id="appendices-legacy-exceptions-var-const">9.4.2.3 Use @const for constants variables</h5>
3449 <h4 id="appendices-legacy-exceptions-function">9.4.3 Do not use block scoped functions declarations…
3453 <pre><code class="language-js prettyprint badcode">if (x) {
3460 inconsistent with each other and with the now-standard ECMAScript 6 behavior for
3468 <pre><code class="language-js prettyprint">if (x) {
3473 <h4 id="appendices-legacy-exceptions-goog-provide">9.4.4 Dependency management with <code>goog.prov…
3475 <h5 id="appendices-legacy-exceptions-goog-provide-summary">9.4.4.1 Summary</h5>
3479 <a href="#source-file-structure"><code>goog.module</code></a>. The following rules are for
3480 pre-existing <code>goog.provide</code> files only.</p>
3488 <li>Only provide top-level symbols.</li>
3501 <pre><code class="language-js prettyprint">goog.provide('namespace.MyClass');
3512 <p>All members defined on a class should be in the same file. Only top-level
3518 <pre><code class="language-js prettyprint">goog.provide('namespace.MyClass');
3523 <pre><code class="language-js prettyprint badcode">goog.provide('namespace.MyClass');
3533 <pre><code class="language-js prettyprint">goog.provide('foo.bar');
3538 <h5 id="appendices-legacy-exceptions-goog-scope">9.4.4.2 Aliasing with <code>goog.scope</code></h5>
3551 or top-level comments. The invocation must be closed on the last line in the
3558 <p>Only make aliases for names that will not be re-assigned to another object
3562 <pre><code class="language-js prettyprint badcode">goog.scope(function() {
3571 <pre><code class="language-js prettyprint">goog.provide('my.module.SomeType');
3587 this.button = new Button(dom.getElement('my-button'));
3593 <h5 id="appendices-legacy-exceptions-forward-declare">9.4.4.3 <code>goog.forwardDeclare</code></h5>