1 <!DOCTYPE html> 2 <html lang="en"> 3 <head> 4 <meta charset="utf-8"> 5 <title>Google JavaScript Style Guide</title> 6 <link rel="stylesheet" href="javaguide.css"> 7 <script src="include/styleguide.js"></script> 8 <link rel="shortcut icon" href="https://www.google.com/favicon.ico"> 9 <script src="include/jsguide.js"></script> 10 </head> 11 <body onload="initStyleGuide();"> 12 <div id="content"> 13 <h1>Google JavaScript Style Guide</h1> 14 <h2 id="introduction">1 Introduction</h2> 15 16 <p>This document serves as the <strong>complete</strong> definition of Google’s coding standards 17 for source code in the JavaScript programming language. A JavaScript source file 18 is described as being <em>in Google Style</em> if and only if it adheres to the rules 19 herein.</p> 20 21 <p>Like other programming style guides, the issues covered span not only aesthetic 22 issues of formatting, but other types of conventions or coding standards as 23 well. However, this document focuses primarily on the hard-and-fast rules that 24 we follow universally, and avoids giving advice that isn't clearly enforceable 25 (whether by human or tool). </p> 26 27 <h3 id="terminology-notes">1.1 Terminology notes</h3> 28 29 <p>In this document, unless otherwise clarified:</p> 30 31 <ol> 32 <li><p>The term <em>comment</em> always refers to <em>implementation</em> comments. We do not use 33 the phrase <q>documentation comments</q>, instead using the common term “JSDoc” 34 for both human-readable text and machine-readable annotations within 35 <code>/** … */</code>.</p></li> 36 <li><p>This Style Guide uses <a href="http://tools.ietf.org/html/rfc2119">RFC 2119</a> terminology when using the phrases <em>must</em>, 37 <em>must not</em>, <em>should</em>, <em>should not</em>, and <em>may</em>. The terms <em>prefer</em> and 38 <em>avoid</em> correspond to <em>should</em> and <em>should not</em>, respectively. Imperative 39 and declarative statements are prescriptive and correspond to <em>must</em>.</p></li> 40 </ol> 41 42 <p>Other <q>terminology notes</q> will appear occasionally throughout the document.</p> 43 44 <h3 id="guide-notes">1.2 Guide notes</h3> 45 46 <p>Example code in this document is <strong>non-normative</strong>. That is, while the examples 47 are in Google Style, they may not illustrate the <em>only</em> stylish way to represent 48 the code. Optional formatting choices made in examples must not be enforced as 49 rules.</p> 50 51 <h2 id="source-file-basics">2 Source file basics</h2> 52 53 <h3 id="file-name">2.1 File name</h3> 54 55 <p>File names must be all lowercase and may include underscores (<code>_</code>) or dashes 56 (<code>-</code>), but no additional punctuation. Follow the convention that your project 57 uses. Filenames’ extension must be <code>.js</code>.</p> 58 59 <h3 id="file-encoding">2.2 File encoding: UTF-8</h3> 60 61 <p>Source files are encoded in <strong>UTF-8</strong>.</p> 62 63 <h3 id="special-characters">2.3 Special characters</h3> 64 65 <h4 id="whitespace-characters">2.3.1 Whitespace characters</h4> 66 67 <p>Aside from the line terminator sequence, the ASCII horizontal space character 68 (0x20) is the only whitespace character that appears anywhere in a source 69 file. This implies that</p> 70 71 <ol> 72 <li><p>All other whitespace characters in string literals are escaped, and</p></li> 73 <li><p>Tab characters are <strong>not</strong> used for indentation.</p></li> 74 </ol> 75 76 <h4 id="special-escape-sequences">2.3.2 Special escape sequences</h4> 77 78 <p>For any character that has a special escape sequence (<code>\'</code>, <code>\"</code>, <code>\\</code>, <code>\b</code>, 79 <code>\f</code>, <code>\n</code>, <code>\r</code>, <code>\t</code>, <code>\v</code>), that sequence is used rather than the 80 corresponding numeric escape (e.g <code>\x0a</code>, <code>\u000a</code>, or <code>\u{a}</code>). Legacy octal 81 escapes are never used.</p> 82 83 <h4 id="non-ascii-characters">2.3.3 Non-ASCII characters</h4> 84 85 <p>For the remaining non-ASCII characters, either the actual Unicode character 86 (e.g. <code>∞</code>) or the equivalent hex or Unicode escape (e.g. <code>\u221e</code>) is used, 87 depending only on which makes the code <strong>easier to read and understand</strong>.</p> 88 89 <p>Tip: In the Unicode escape case, and occasionally even when actual Unicode 90 characters are used, an explanatory comment can be very helpful.</p> 91 92 <table> 93 <thead> 94 <tr> 95 <th>Example 96 </th><th>Discussion 97 </th></tr></thead><tbody> 98 <tr> 99 <td><code class="prettyprint lang-js">const units = 'μs';</code> 100 </td><td>Best: perfectly clear even without a comment. 101 </td></tr><tr> 102 <td> 103 <code class="prettyprint lang-js">const units = '\u03bcs'; // 'μs' 104 </code> 105 </td><td>Allowed, but there’s no reason to do this. 106 </td></tr><tr> 107 <td> 108 <code class="prettyprint lang-js">const units = '\u03bcs'; // Greek letter mu, 's' 109 </code> 110 </td><td>Allowed, but awkward and prone to mistakes. 111 </td></tr><tr> 112 <td><code class="badcode">const units = '\u03bcs';</code> 113 </td><td>Poor: the reader has no idea what this is. 114 </td></tr><tr> 115 <td> 116 <code class="prettyprint lang-js">return '\ufeff' + content; // byte order mark 117 </code> 118 </td><td> 119 Good: use escapes for non-printable characters, and comment if 120 necessary. 121 </td></tr></tbody></table> 122 123 <p>Tip: Never make your code less readable simply out of fear that some programs 124 might not handle non-ASCII characters properly. If that happens, those programs 125 are <strong>broken</strong> and they must be <strong>fixed</strong>.</p> 126 127 <h2 id="source-file-structure">3 Source file structure</h2> 128 129 <p>A source file consists of, <strong>in order</strong>:</p> 130 131 <ol> 132 <li>License or copyright information, if present</li> 133 <li><code>@fileoverview</code> JSDoc, if present</li> 134 <li><code>goog.module</code> statement</li> 135 <li><code>goog.require</code> statements</li> 136 <li>The file’s implementation</li> 137 </ol> 138 139 <p><strong>Exactly one blank line</strong> separates each section that is present, except the 140 file's implementation, which may be preceded by 1 or 2 blank lines.</p> 141 142 <h3 id="file-copyright">3.1 License or copyright information, if present</h3> 143 144 <p>If license or copyright information belongs in a file, it belongs here.</p> 145 146 <h3 id="file-fileoverview">3.2 <code>@fileoverview</code> JSDoc, if present</h3> 147 148 <p>See <a href="#jsdoc-top-file-level-comments">??</a> for formatting rules.</p> 149 150 <h3 id="file-goog-module">3.3 <code>goog.module</code> statement</h3> 151 152 <p>All files must declare exactly one <code>goog.module</code> name on a single line: lines 153 containing a <code>goog.module</code> declaration must not be wrapped, and are therefore an 154 exception to the 80-column limit.</p> 155 156 <p>The entire argument to goog.module is what defines a namespace. It is the 157 package name (an identifier that reflects the fragment of the directory 158 structure where the code lives) plus, optionally, the main class/enum/interface 159 that it defines concatenated to the end.</p> 160 161 <p>Example</p> 162 163 <pre><code class="language-js prettyprint">goog.module('search.urlHistory.UrlHistoryService'); 164 </code></pre> 165 166 <h4 id="naming-hierarchy">3.3.1 Hierarchy</h4> 167 168 <p>Module namespaces may never be named as a <em>direct</em> child of another module's 169 namespace.</p> 170 171 <p>Illegal:</p> 172 173 <pre><code class="language-js prettyprint badcode">goog.module('foo.bar'); // 'foo.bar.qux' would be fine, though 174 goog.module('foo.bar.baz'); 175 </code></pre> 176 177 <p>The directory hierarchy reflects the namespace hierarchy, so that deeper-nested 178 children are subdirectories of higher-level parent directories. Note that this 179 implies that owners of “parent” namespace groups are necessarily aware of all 180 child namespaces, since they exist in the same directory.</p> 181 182 <h4 id="file-set-test-only">3.3.2 <code>goog.setTestOnly</code></h4> 183 184 <p>The single <code>goog.module</code> statement may optionally be followed by a call to 185 goog.setTestOnly().</p> 186 187 <h4 id="file-declare-legacy-namespace">3.3.3 <code>goog.module.declareLegacyNamespace</code></h4> 188 189 <p>The single <code>goog.module</code> statement may optionally be followed by a call to 190 <code>goog.module.declareLegacyNamespace();</code>. Avoid 191 <code>goog.module.declareLegacyNamespace()</code> when possible.</p> 192 193 <p>Example:</p> 194 195 <pre><code class="language-js prettyprint">goog.module('my.test.helpers'); 196 goog.module.declareLegacyNamespace(); 197 goog.setTestOnly(); 198 </code></pre> 199 200 <p><code>goog.module.declareLegacyNamespace</code> exists to ease the transition from 201 traditional object hierarchy-based namespaces but comes with some naming 202 restrictions. As the child module name must be created after the parent 203 namespace, this name <strong>must not</strong> be a child or parent of any other 204 <code>goog.module</code> (for example, <code>goog.module('parent');</code> and 205 <code>goog.module('parent.child');</code> cannot both exist safely, nor can 206 <code>goog.module('parent');</code> and <code>goog.module('parent.child.grandchild');</code>).</p> 207 208 <h4 id="file-es6-modules">3.3.4 ES6 Modules</h4> 209 210 <p>Do not use ES6 modules yet (i.e. the <code>export</code> and <code>import</code> keywords), as their 211 semantics are not yet finalized. Note that this policy will be revisited once 212 the semantics are fully-standard.</p> 213 214 <h3 id="file-goog-require">3.4 <code>goog.require</code> statements</h3> 215 216 <p>Imports are done with <code>goog.require</code> statements, grouped together immediately 217 following the module declaration. Each <code>goog.require</code> is assigned to a single 218 constant alias, or else destructured into several constant aliases. These 219 aliases are the only acceptable way to refer to the <code>require</code>d dependency, 220 whether in code or in type annotations: the fully qualified name is never used 221 except as the argument to <code>goog.require</code>. Alias names should match the final 222 dot-separated component of the imported module name when possible, though 223 additional components may be included (with appropriate casing such that the 224 alias' casing still correctly identifies its type) if necessary to 225 disambiguate, or if it significantly improves readability. <code>goog.require</code> 226 statements may not appear anywhere else in the file.</p> 227 228 <p>If a module is imported only for its side effects, the assignment may be 229 omitted, but the fully qualified name may not appear anywhere else in the file. 230 A comment is required to explain why this is needed and suppress a compiler 231 warning.</p> 232 233 234 235 <p>The lines are sorted according to the following rules: All requires with a name 236 on the left hand side come first, sorted alphabetically by those names. Then 237 destructuring requires, again sorted by the names on the left hand side. 238 Finally, any <code>goog.require</code> calls that are standalone (generally these are for 239 modules imported just for their side effects).</p> 240 241 <p>Tip: There’s no need to memorize this order and enforce it manually. You can 242 rely on your IDE to report requires 243 that are not sorted correctly.</p> 244 245 <p>If a long alias or module name would cause a line to exceed the 80-column limit, 246 it <strong>must not</strong> be wrapped: goog.require lines are an exception to the 80-column 247 limit.</p> 248 249 <p>Example:</p> 250 251 <pre><code class="language-js prettyprint">const MyClass = goog.require('some.package.MyClass'); 252 const NsMyClass = goog.require('other.ns.MyClass'); 253 const googAsserts = goog.require('goog.asserts'); 254 const testingAsserts = goog.require('goog.testing.asserts'); 255 const than80columns = goog.require('pretend.this.is.longer.than80columns'); 256 const {clear, forEach, map} = goog.require('goog.array'); 257 /** @suppress {extraRequire} Initializes MyFramework. */ 258 goog.require('my.framework.initialization'); 259 </code></pre> 260 261 <p>Illegal:</p> 262 263 <pre><code class="language-js badcode prettyprint">const randomName = goog.require('something.else'); // name must match 264 265 const {clear, forEach, map} = // don't break lines 266 goog.require('goog.array'); 267 268 function someFunction() { 269 const alias = goog.require('my.long.name.alias'); // must be at top level 270 // … 271 } 272 </code></pre> 273 274 <h4 id="file-goog-forward-declare">3.4.1 <code>goog.forwardDeclare</code></h4> 275 276 <p><code>goog.forwardDeclare</code> is not needed very often, but is a valuable tool to break 277 circular dependencies or to reference late loaded code. These statements are 278 grouped together and immediately follow any <code>goog.require</code> statements. A 279 <code>goog.forwardDeclare</code> statement must follow the same style rules as a 280 <code>goog.require</code> statement.</p> 281 282 <h3 id="file-implementation">3.5 The file’s implementation</h3> 283 284 <p>The actual implementation follows after all dependency information is declared 285 (separated by at least one blank line).</p> 286 287 <p>This may consist of any module-local declarations (constants, variables, 288 classes, functions, etc), as well as any exported symbols. 289 </p> 290 291 <h2 id="formatting">4 Formatting</h2> 292 293 <p><strong>Terminology Note</strong>: <em>block-like construct</em> refers to the body of a class, 294 function, method, or brace-delimited block of code. Note that, by 295 <a href="#features-array-literals">??</a> and <a href="#features-object-literals">??</a>, any array or 296 object literal may optionally be treated as if it were a block-like construct.</p> 297 298 <p>Tip: Use <code>clang-format</code>. The JavaScript community has invested effort to make 299 sure clang-format <q>does the right thing</q> on JavaScript files. <code>clang-format</code> has 300 integration with several popular 301 editors.</p> 302 303 <h3 id="formatting-braces">4.1 Braces</h3> 304 305 <h4 id="formatting-braces-all">4.1.1 Braces are used for all control structures</h4> 306 307 <p>Braces are required for all control structures (i.e. <code>if</code>, <code>else</code>, <code>for</code>, <code>do</code>, 308 <code>while</code>, as well as any others), even if the body contains only a single 309 statement. The first statement of a non-empty block must begin on its own line.</p> 310 311 <p>Illegal:</p> 312 313 <pre><code class="language-js badcode prettyprint">if (someVeryLongCondition()) 314 doSomething(); 315 316 for (let i = 0; i < foo.length; i++) bar(foo[i]); 317 </code></pre> 318 319 <p><strong>Exception</strong>: A simple if statement that can fit entirely on a single line with 320 no wrapping (and that doesn’t have an else) may be kept on a single line with no 321 braces when it improves readability. This is the only case in which a control 322 structure may omit braces and newlines.</p> 323 324 <pre><code class="language-js prettyprint">if (shortCondition()) return; 325 </code></pre> 326 327 <h4 id="formatting-nonempty-blocks">4.1.2 Nonempty blocks: K&R style</h4> 328 329 <p>Braces follow the Kernighan and Ritchie style (<q><a href="http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html">Egyptian brackets</a></q>) for 330 <em>nonempty</em> blocks and block-like constructs:</p> 331 332 <ul> 333 <li>No line break before the opening brace.</li> 334 <li>Line break after the opening brace.</li> 335 <li>Line break before the closing brace.</li> 336 <li>Line break after the closing brace <em>if</em> that brace terminates a statement or 337 the body of a function or class statement, or a class method. Specifically, 338 there is <em>no</em> line break after the brace if it is followed by <code>else</code>, <code>catch</code>, 339 <code>while</code>, or a comma, semicolon, or right-parenthesis.</li> 340 </ul> 341 342 <p>Example:</p> 343 344 <pre><code class="language-js prettyprint">class InnerClass { 345 constructor() {} 346 347 /** @param {number} foo */ 348 method(foo) { 349 if (condition(foo)) { 350 try { 351 // Note: this might fail. 352 something(); 353 } catch (err) { 354 recover(); 355 } 356 } 357 } 358 } 359 </code></pre> 360 361 <h4 id="formatting-empty-blocks">4.1.3 Empty blocks: may be concise</h4> 362 363 <p>An empty block or block-like construct <em>may</em> be closed immediately after it is 364 opened, with no characters, space, or line break in between (i.e. <code>{}</code>), 365 <strong>unless</strong> it is a part of a <em>multi-block statement</em> (one that directly contains 366 multiple blocks: <code>if</code>/<code>else</code> or <code>try</code>/<code>catch</code>/<code>finally</code>).</p> 367 368 <p>Example:</p> 369 370 <pre><code class="language-js prettyprint">function doNothing() {} 371 </code></pre> 372 373 <p>Illegal:</p> 374 375 <pre><code class="language-js prettyprint badcode">if (condition) { 376 // … 377 } else if (otherCondition) {} else { 378 // … 379 } 380 381 try { 382 // … 383 } catch (e) {} 384 </code></pre> 385 386 <h3 id="formatting-block-indentation">4.2 Block indentation: +2 spaces</h3> 387 388 <p>Each time a new block or block-like construct is opened, the indent increases by 389 two spaces. When the block ends, the indent returns to the previous indent 390 level. The indent level applies to both code and comments throughout the 391 block. (See the example in <a href="#formatting-nonempty-blocks">??</a>).</p> 392 393 <h4 id="formatting-array-literals">4.2.1 Array literals: optionally <q>block-like</q></h4> 394 395 <p>Any array literal may optionally be formatted as if it were a “block-like 396 construct.” For example, the following are all valid (<strong>not</strong> an exhaustive 397 list):</p> 398 399 <pre><code class="language-js prettyprint columns">const a = [ 400 0, 401 1, 402 2, 403 ]; 404 405 const b = 406 [0, 1, 2]; 407 408 </code></pre> 409 410 <pre><code class="language-js prettyprint columns">const c = [0, 1, 2]; 411 412 someMethod(foo, [ 413 0, 1, 2, 414 ], bar); 415 </code></pre> 416 417 <p>Other combinations are allowed, particularly when emphasizing semantic groupings 418 between elements, but should not be used only to reduce the vertical size of 419 larger arrays.</p> 420 421 <h4 id="formatting-object-literals">4.2.2 Object literals: optionally <q>block-like</q></h4> 422 423 <p>Any object literal may optionally be formatted as if it were a “block-like 424 construct.” The same examples apply as <a href="#formatting-array-literals">??</a>. For 425 example, the following are all valid (<strong>not</strong> an exhaustive list):</p> 426 427 <pre><code class="language-js prettyprint columns">const a = { 428 a: 0, 429 b: 1, 430 }; 431 432 const b = 433 {a: 0, b: 1}; 434 </code></pre> 435 436 <pre><code class="language-js prettyprint columns">const c = {a: 0, b: 1}; 437 438 someMethod(foo, { 439 a: 0, b: 1, 440 }, bar); 441 </code></pre> 442 443 <h4 id="formatting-class-literals">4.2.3 Class literals</h4> 444 445 <p>Class literals (whether declarations or expressions) are indented as blocks. Do 446 not add semicolons after methods, or after the closing brace of a class 447 <em>declaration</em> (statements—such as assignments—that contain class <em>expressions</em> 448 are still terminated with a semicolon). Use the <code>extends</code> keyword, but not the 449 <code>@extends</code> JSDoc annotation unless the class extends a templatized type.</p> 450 451 <p>Example:</p> 452 453 <pre><code class="language-js prettyprint columns">class Foo { 454 constructor() { 455 /** @type {number} */ 456 this.x = 42; 457 } 458 459 /** @return {number} */ 460 method() { 461 return this.x; 462 } 463 } 464 Foo.Empty = class {}; 465 </code></pre> 466 467 <pre><code class="language-js prettyprint columns">/** @extends {Foo<string>} */ 468 foo.Bar = class extends Foo { 469 /** @override */ 470 method() { 471 return super.method() / 2; 472 } 473 }; 474 475 /** @interface */ 476 class Frobnicator { 477 /** @param {string} message */ 478 frobnicate(message) {} 479 } 480 </code></pre> 481 482 <h4 id="formatting-function-expressions">4.2.4 Function expressions</h4> 483 484 <p>When declaring an anonymous function in the list of arguments for a function 485 call, the body of the function is indented two spaces more than the preceding 486 indentation depth.</p> 487 488 <p>Example:</p> 489 490 <pre><code class="language-js prettyprint">prefix.something.reallyLongFunctionName('whatever', (a1, a2) => { 491 // Indent the function body +2 relative to indentation depth 492 // of the 'prefix' statement one line above. 493 if (a1.equals(a2)) { 494 someOtherLongFunctionName(a1); 495 } else { 496 andNowForSomethingCompletelyDifferent(a2.parrot); 497 } 498 }); 499 500 some.reallyLongFunctionCall(arg1, arg2, arg3) 501 .thatsWrapped() 502 .then((result) => { 503 // Indent the function body +2 relative to the indentation depth 504 // of the '.then()' call. 505 if (result) { 506 result.use(); 507 } 508 }); 509 </code></pre> 510 511 <h4 id="formatting-switch-statements">4.2.5 Switch statements</h4> 512 513 <p>As with any other block, the contents of a switch block are indented +2.</p> 514 515 516 517 <p>After a switch label, a newline appears, and the indentation level is increased 518 +2, exactly as if a block were being opened. An explicit block may be used if 519 required by lexical scoping. The following switch label returns to the previous 520 indentation level, as if a block had been closed.</p> 521 522 <p>A blank line is optional between a <code>break</code> and the following case.</p> 523 524 <p>Example:</p> 525 526 <pre><code class="language-js prettyprint">switch (animal) { 527 case Animal.BANDERSNATCH: 528 handleBandersnatch(); 529 break; 530 531 case Animal.JABBERWOCK: 532 handleJabberwock(); 533 break; 534 535 default: 536 throw new Error('Unknown animal'); 537 } 538 </code></pre> 539 540 <h3 id="formatting-statements">4.3 Statements</h3> 541 542 <h4 id="formatting-one-statement-perline">4.3.1 One statement per line</h4> 543 544 <p>Each statement is followed by a line-break.</p> 545 546 <h4 id="formatting-semicolons-are-required">4.3.2 Semicolons are required</h4> 547 548 <p>Every statement must be terminated with a semicolon. Relying on automatic 549 semicolon insertion is forbidden.</p> 550 551 <h3 id="formatting-column-limit">4.4 Column limit: 80</h3> 552 553 <p>JavaScript code has a column limit of 80 characters. Except as noted below, any 554 line that would exceed this limit must be line-wrapped, as explained in 555 <a href="#formatting-line-wrapping">??</a>.</p> 556 557 <p><strong>Exceptions:</strong></p> 558 559 <ol> 560 <li>Lines where obeying the column limit is not possible (for example, a long URL 561 in JSDoc or a shell command intended to be copied-and-pasted).</li> 562 <li><code>goog.module</code> and <code>goog.require</code> statements (see <a href="#file-goog-module">??</a> and 563 <a href="#file-goog-require">??</a>).</li> 564 </ol> 565 566 <h3 id="formatting-line-wrapping">4.5 Line-wrapping</h3> 567 568 <p><strong>Terminology Note</strong>: <em>Line-wrapping</em> is defined as breaking a single expression 569 into multiple lines.</p> 570 571 <p>There is no comprehensive, deterministic formula showing <em>exactly</em> how to 572 line-wrap in every situation. Very often there are several valid ways to 573 line-wrap the same piece of code.</p> 574 575 <p>Note: While the typical reason for line-wrapping is to avoid overflowing the 576 column limit, even code that would in fact fit within the column limit may be 577 line-wrapped at the author's discretion.</p> 578 579 <p>Tip: Extracting a method or local variable may solve the problem without the 580 need to line-wrap.</p> 581 582 <h4 id="formatting-where-to-break">4.5.1 Where to break</h4> 583 584 <p>The prime directive of line-wrapping is: prefer to break at a <strong>higher syntactic 585 level</strong>. </p> 586 587 <p>Preferred:</p> 588 589 <pre><code class="language-js prettyprint">currentEstimate = 590 calc(currentEstimate + x * currentEstimate) / 591 2.0f; 592 </code></pre> 593 594 <p>Discouraged:</p> 595 596 <pre><code class="language-js prettyprint badcode">currentEstimate = calc(currentEstimate + x * 597 currentEstimate) / 2.0f; 598 </code></pre> 599 600 <p>In the preceding example, the syntactic levels from highest to lowest are as 601 follows: assignment, division, function call, parameters, number constant.</p> 602 603 <p>Operators are wrapped as follows:</p> 604 605 <ol> 606 <li>When a line is broken at an operator the break comes after the symbol. (Note 607 that this is not the same practice used in Google style for Java.) 608 <ol> 609 <li>This does not apply to the <q>dot</q> (<code>.</code>), which is not actually an 610 operator.</li> 611 </ol></li> 612 <li>A method or constructor name stays attached to the open parenthesis (<code>(</code>) 613 that follows it.</li> 614 <li>A comma (<code>,</code>) stays attached to the token that precedes it.</li> 615 </ol> 616 617 <blockquote> 618 <p>Note: The primary goal for line wrapping is to have clear code, not 619 necessarily code that fits in the smallest number of lines.</p> 620 </blockquote> 621 622 <h4 id="formatting-indent">4.5.2 Indent continuation lines at least +4 spaces</h4> 623 624 <p>When line-wrapping, each line after the first (each <em>continuation line</em>) is 625 indented at least +4 from the original line, unless it falls under the rules of 626 block indentation.</p> 627 628 <p>When there are multiple continuation lines, indentation may be varied beyond +4 629 as appropriate. In general, continuation lines at a deeper syntactic level are 630 indented by larger multiples of 4, and two lines use the same indentation level 631 if and only if they begin with syntactically parallel elements.</p> 632 633 <p><a href="#formatting-horizontal-alignment">??</a> addresses the discouraged practice of 634 using a variable number of spaces to align certain tokens with previous lines.</p> 635 636 <h3 id="formatting-whitespace">4.6 Whitespace</h3> 637 638 <h4 id="formatting-vertical-whitespace">4.6.1 Vertical whitespace</h4> 639 640 <p>A single blank line appears:</p> 641 642 <ol> 643 <li>Between consecutive methods in a class or object literal 644 <ol> 645 <li>Exception: A blank line between two consecutive properties definitions in 646 an object literal (with no other code between them) is optional. Such 647 blank lines are used as needed to create <em>logical groupings</em> of fields.</li> 648 </ol></li> 649 <li>Within method bodies, sparingly to create <em>logical groupings</em> of statements. 650 Blank lines at the start or end of a function body are not allowed.</li> 651 <li><em>Optionally</em> before the first or after the last method in a class or object 652 literal (neither encouraged nor discouraged).</li> 653 <li>As required by other sections of this document (e.g. 654 <a href="#file-goog-require">??</a>).</li> 655 </ol> 656 657 <p><em>Multiple</em> consecutive blank lines are permitted, but never required (nor 658 encouraged).</p> 659 660 <h4 id="formatting-horizontal-whitespace">4.6.2 Horizontal whitespace</h4> 661 662 <p>Use of horizontal whitespace depends on location, and falls into three broad 663 categories: <em>leading</em> (at the start of a line), <em>trailing</em> (at the end of a 664 line), and <em>internal</em>. Leading whitespace (i.e., indentation) is addressed 665 elsewhere. Trailing whitespace is forbidden.</p> 666 667 <p>Beyond where required by the language or other style rules, and apart from 668 literals, comments, and JSDoc, a single internal ASCII space also appears in the 669 following places <strong>only</strong>.</p> 670 671 <ol> 672 <li>Separating any reserved word (such as <code>if</code>, <code>for</code>, or <code>catch</code>) from an open 673 parenthesis (<code>(</code>) that follows it on that line.</li> 674 <li>Separating any reserved word (such as <code>else</code> or <code>catch</code>) from a closing 675 curly brace (<code>}</code>) that precedes it on that line.</li> 676 <li>Before any open curly brace (<code>{</code>), with two exceptions: 677 <ol> 678 <li>Before an object literal that is the first argument of a function or the 679 first element in an array literal (e.g. <code>foo({a: [{c: d}]})</code>).</li> 680 <li>In a template expansion, as it is forbidden by the language 681 (e.g. <code>abc${1 + 2}def</code>).</li> 682 </ol></li> 683 <li>On both sides of any binary or ternary operator.</li> 684 <li>After a comma (<code>,</code>) or semicolon (<code>;</code>). Note that spaces are <em>never</em> allowed 685 before these characters.</li> 686 <li>After the colon (<code>:</code>) in an object literal.</li> 687 <li>On both sides of the double slash (<code>//</code>) that begins an end-of-line 688 comment. Here, multiple spaces are allowed, but not required.</li> 689 <li>After an open-JSDoc comment character and on both sides of close characters 690 (e.g. for short-form type declarations or casts: <code>this.foo = /** @type 691 {number} */ (bar);</code> or <code>function(/** string */ foo) {</code>).</li> 692 </ol> 693 694 <h4 id="formatting-horizontal-alignment">4.6.3 Horizontal alignment: discouraged</h4> 695 696 <p><strong>Terminology Note</strong>: <em>Horizontal alignment</em> is the practice of adding a 697 variable number of additional spaces in your code with the goal of making 698 certain tokens appear directly below certain other tokens on previous lines.</p> 699 700 <p>This practice is permitted, but it is <strong>generally discouraged</strong> by Google 701 Style. It is not even required to <em>maintain</em> horizontal alignment in places 702 where it was already used.</p> 703 704 <p>Here is an example without alignment, followed by one with alignment. Both are 705 allowed, but the latter is discouraged:</p> 706 707 <pre><code class="language-js prettyprint">{ 708 tiny: 42, // this is great 709 longer: 435, // this too 710 }; 711 712 { 713 tiny: 42, // permitted, but future edits 714 longer: 435, // may leave it unaligned 715 }; 716 </code></pre> 717 718 <p>Tip: Alignment can aid readability, but it creates problems for future 719 maintenance. Consider a future change that needs to touch just one line. This 720 change may leave the formerly-pleasing formatting mangled, and that is 721 allowed. More often it prompts the coder (perhaps you) to adjust whitespace on 722 nearby lines as well, possibly triggering a cascading series of 723 reformattings. That one-line change now has a <q>blast radius.</q> This can at worst 724 result in pointless busywork, but at best it still corrupts version history 725 information, slows down reviewers and exacerbates merge conflicts.</p> 726 727 <h4 id="formatting-function-arguments">4.6.4 Function arguments</h4> 728 729 <p>Prefer to put all function arguments on the same line as the function name. If doing so would exceed the 80-column limit, the arguments must be line-wrapped in a readable way. To save space, you may wrap as close to 80 as possible, or put each argument on its own line to enhance readability. Indentation should be four spaces. Aligning to the parenthesis is allowed, but discouraged. Below are the most common patterns for argument wrapping:</p> 730 731 <pre><code class="language-js prettyprint">// Arguments start on a new line, indented four spaces. Preferred when the 732 // arguments don't fit on the same line with the function name (or the keyword 733 // "function") but fit entirely on the second line. Works with very long 734 // function names, survives renaming without reindenting, low on space. 735 doSomething( 736 descriptiveArgumentOne, descriptiveArgumentTwo, descriptiveArgumentThree) { 737 // … 738 } 739 740 // If the argument list is longer, wrap at 80. Uses less vertical space, 741 // but violates the rectangle rule and is thus not recommended. 742 doSomething(veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo, 743 tableModelEventHandlerProxy, artichokeDescriptorAdapterIterator) { 744 // … 745 } 746 747 // Four-space, one argument per line. Works with long function names, 748 // survives renaming, and emphasizes each argument. 749 doSomething( 750 veryDescriptiveArgumentNumberOne, 751 veryDescriptiveArgumentTwo, 752 tableModelEventHandlerProxy, 753 artichokeDescriptorAdapterIterator) { 754 // … 755 } 756 </code></pre> 757 758 <h3 id="formatting-grouping-parentheses">4.7 Grouping parentheses: recommended</h3> 759 760 <p>Optional grouping parentheses are omitted only when the author and reviewer 761 agree that there is no reasonable chance that the code will be misinterpreted 762 without them, nor would they have made the code easier to read. It is <em>not</em> 763 reasonable to assume that every reader has the entire operator precedence table 764 memorized.</p> 765 766 <p>Do not use unnecessary parentheses around the entire expression following 767 <code>delete</code>, <code>typeof</code>, <code>void</code>, <code>return</code>, <code>throw</code>, <code>case</code>, <code>in</code>, <code>of</code>, or <code>yield</code>.</p> 768 769 <p>Parentheses are required for type casts: <code>/** @type {!Foo} */ (foo)</code>.</p> 770 771 <h3 id="formatting-comments">4.8 Comments</h3> 772 773 <p>This section addresses <em>implementation comments</em>. JSDoc is addressed separately 774 in <a href="#jsdoc">??</a>.</p> 775 776 <h4 id="formatting-block-comment-style">4.8.1 Block comment style</h4> 777 778 <p>Block comments are indented at the same level as the surrounding code. They may 779 be in <code>/* … */</code> or <code>//</code>-style. For multi-line <code>/* … */</code> comments, subsequent 780 lines must start with * aligned with the <code>*</code> on the previous line, to make 781 comments obvious with no extra context. “Parameter name” comments should appear 782 after values whenever the value and method name do not sufficiently convey the 783 meaning.</p> 784 785 <pre><code class="language-js prettyprint">/* 786 * This is 787 * okay. 788 */ 789 790 // And so 791 // is this. 792 793 /* This is fine, too. */ 794 795 someFunction(obviousParam, true /* shouldRender */, 'hello' /* name */); 796 </code></pre> 797 798 <p>Comments are not enclosed in boxes drawn with asterisks or other characters.</p> 799 800 <p>Do not use JSDoc (<code>/** … */</code>) for any of the above implementation comments.</p> 801 802 <h2 id="language-features">5 Language features</h2> 803 804 <p>JavaScript includes many dubious (and even dangerous) features. This section 805 delineates which features may or may not be used, and any additional constraints 806 on their use.</p> 807 808 <h3 id="features-local-variable-declarations">5.1 Local variable declarations</h3> 809 810 <h4 id="features-use-const-and-let">5.1.1 Use <code>const</code> and <code>let</code></h4> 811 812 <p>Declare all local variables with either <code>const</code> or <code>let</code>. Use const by default, 813 unless a variable needs to be reassigned. The <code class="badcode">var</code> 814 keyword must not be used.</p> 815 816 <h4 id="features-one-variable-per-declaration">5.1.2 One variable per declaration</h4> 817 818 <p>Every local variable declaration declares only one variable: declarations such 819 as <code class="badcode">let a = 1, b = 2;</code> are not used.</p> 820 821 <h4 id="features-declared-when-needed">5.1.3 Declared when needed, initialized as soon as possible</h4> 822 823 <p>Local variables are <strong>not</strong> habitually declared at the start of their containing 824 block or block-like construct. Instead, local variables are declared close to 825 the point they are first used (within reason), to minimize their scope.</p> 826 827 <h4 id="features-declare-types-as-needed">5.1.4 Declare types as needed</h4> 828 829 <p>JSDoc type annotations may be added either on the line above the declaration, or 830 else inline before the variable name.</p> 831 832 <p>Example:</p> 833 834 <pre><code class="language-js prettyprint">const /** !Array<number> */ data = []; 835 836 /** @type {!Array<number>} */ 837 const data = []; 838 </code></pre> 839 840 <p>Tip: There are many cases where the compiler can infer a templatized type but 841 not its parameters. This is particularly the case when the initializing literal 842 or constructor call does not include any values of the template parameter type 843 (e.g., empty arrays, objects, <code>Map</code>s, or <code>Set</code>s), or if the variable is modified 844 in a closure. Local variable type annotations are particularly helpful in these 845 cases since otherwise the compiler will infer the template parameter as unknown.</p> 846 847 <h3 id="features-array-literals">5.2 Array literals</h3> 848 849 <h4 id="features-arrays-trailing-comma">5.2.1 Use trailing commas</h4> 850 851 852 853 <p>Include a trailing comma whenever there is a line break between the final 854 element and the closing bracket.</p> 855 856 <p>Example:</p> 857 858 <pre><code class="language-js prettyprint">const values = [ 859 'first value', 860 'second value', 861 ]; 862 </code></pre> 863 864 <h4 id="features-arrays-ctor">5.2.2 Do not use the variadic <code>Array</code> constructor</h4> 865 866 <p>The constructor is error-prone if arguments are added or removed. Use a literal 867 instead.</p> 868 869 <p>Illegal:</p> 870 871 <pre><code class="language-js prettyprint badcode">const a1 = new Array(x1, x2, x3); 872 const a2 = new Array(x1, x2); 873 const a3 = new Array(x1); 874 const a4 = new Array(); 875 </code></pre> 876 877 <p>This works as expected except for the third case: if <code>x1</code> is a whole number then 878 <code>a3</code> is an array of size <code>x1</code> where all elements are <code>undefined</code>. If <code>x1</code> is any 879 other number, then an exception will be thrown, and if it is anything else then 880 it will be a single-element array.</p> 881 882 <p>Instead, write</p> 883 884 <pre><code class="language-js prettyprint">const a1 = [x1, x2, x3]; 885 const a2 = [x1, x2]; 886 const a3 = [x1]; 887 const a4 = []; 888 </code></pre> 889 890 <p>Explicitly allocating an array of a given length using <code>new Array(length)</code> is 891 allowed when appropriate.</p> 892 893 <h4 id="features-arrays-non-numeric-properties">5.2.3 Non-numeric properties</h4> 894 895 <p>Do not define or use non-numeric properties on an array (other than 896 <code>length</code>). Use a <code>Map</code> (or <code>Object</code>) instead.</p> 897 898 <h4 id="features-arrays-destructuring">5.2.4 Destructuring</h4> 899 900 <p>Array literals may be used on the left-hand side of an assignment to perform 901 destructuring (such as when unpacking multiple values from a single array or 902 iterable). A final <q>rest</q> element may be included (with no space between the 903 <code>...</code> and the variable name). Elements should be omitted if they are unused.</p> 904 905 <pre><code class="language-js prettyprint">const [a, b, c, ...rest] = generateResults(); 906 let [, b,, d] = someArray; 907 </code></pre> 908 909 <p>Destructuring may also be used for function parameters (note that a parameter 910 name is required but ignored). Always specify <code>[]</code> as the default value if a 911 destructured array parameter is optional, and provide default values on the left 912 hand side:</p> 913 914 <pre><code class="language-js prettyprint">/** @param {!Array<number>=} param1 */ 915 function optionalDestructuring([a = 4, b = 2] = []) { … }; 916 </code></pre> 917 918 <p>Illegal:</p> 919 920 <pre><code class="language-js prettyprint badcode">function badDestructuring([a, b] = [4, 2]) { … }; 921 </code></pre> 922 923 <p>Tip: For (un)packing multiple values into a function’s parameter or return, 924 prefer object destructuring to array destructuring when possible, as it allows 925 naming the individual elements and specifying a different type for each.*</p> 926 927 <h4 id="features-arrays-spread-operator">5.2.5 Spread operator</h4> 928 929 <p>Array literals may include the spread operator (<code>...</code>) to flatten elements out 930 of one or more other iterables. The spread operator should be used instead of 931 more awkward constructs with <code>Array.prototype</code>. There is no space after the 932 <code>...</code>.</p> 933 934 <p>Example:</p> 935 936 <pre><code class="language-js prettyprint">[...foo] // preferred over Array.prototype.slice.call(foo) 937 [...foo, ...bar] // preferred over foo.concat(bar) 938 </code></pre> 939 940 <h3 id="features-object-literals">5.3 Object literals</h3> 941 942 <h4 id="features-objects-use-trailing-comma">5.3.1 Use trailing commas</h4> 943 944 <p>Include a trailing comma whenever there is a line break between the final 945 property and the closing brace.</p> 946 947 <h4 id="features-objects-ctor">5.3.2 Do not use the <code>Object</code> constructor</h4> 948 949 <p>While <code>Object</code> does not have the same problems as <code>Array</code>, it is still 950 disallowed for consistency. Use an object literal (<code>{}</code> or <code>{a: 0, b: 1, c: 2}</code>) 951 instead.</p> 952 953 <h4 id="features-objects-mixing-keys">5.3.3 Do not mix quoted and unquoted keys</h4> 954 955 <p>Object literals may represent either <em>structs</em> (with unquoted keys and/or 956 symbols) or <em>dicts</em> (with quoted and/or computed keys). Do not mix these key 957 types in a single object literal.</p> 958 959 <p>Illegal:</p> 960 961 <pre><code class="language-js prettyprint badcode">{ 962 a: 42, // struct-style unquoted key 963 'b': 43, // dict-style quoted key 964 } 965 </code></pre> 966 967 <h4 id="features-objects-computed-property-names">5.3.4 Computed property names</h4> 968 969 <p>Computed property names (e.g., <code>{['key' + foo()]: 42}</code>) are allowed, and are 970 considered dict-style (quoted) keys (i.e., must not be mixed with non-quoted 971 keys) unless the computed property is a symbol (e.g., <code>[Symbol.iterator]</code>). 972 Enum values may also be used for computed keys, but should not be mixed with 973 non-enum keys in the same literal.</p> 974 975 <h4 id="features-objects-method-shorthand">5.3.5 Method shorthand</h4> 976 977 <p>Methods can be defined on object literals using the method shorthand (<code>{method() 978 {… }}</code>) in place of a colon immediately followed by a <code>function</code> or arrow 979 function literal.</p> 980 981 <p>Example:</p> 982 983 <pre><code class="language-js prettyprint">return { 984 stuff: 'candy', 985 method() { 986 return this.stuff; // Returns 'candy' 987 }, 988 }; 989 </code></pre> 990 991 <p>Note that <code>this</code> in a method shorthand or <code>function</code> refers to the object 992 literal itself whereas <code>this</code> in an arrow function refers to the scope outside 993 the object literal.</p> 994 995 <p>Example:</p> 996 997 <pre><code class="language-js prettyprint">class { 998 getObjectLiteral() { 999 this.stuff = 'fruit'; 1000 return { 1001 stuff: 'candy', 1002 method: () => this.stuff, // Returns 'fruit' 1003 }; 1004 } 1005 } 1006 </code></pre> 1007 1008 <h4 id="features-objects-shorthand-properties">5.3.6 Shorthand properties</h4> 1009 1010 <p>Shorthand properties are allowed on object literals.</p> 1011 1012 <p>Example:</p> 1013 1014 <pre><code class="language-js prettyprint">const foo = 1; 1015 const bar = 2; 1016 const obj = { 1017 foo, 1018 bar, 1019 method() { return this.foo + this.bar; }, 1020 }; 1021 assertEquals(3, obj.method()); 1022 </code></pre> 1023 1024 <h4 id="features-objects-destructuring">5.3.7 Destructuring</h4> 1025 1026 <p>Object destructuring patterns may be used on the left-hand side of an assignment 1027 to perform destructuring and unpack multiple values from a single object.</p> 1028 1029 <p>Destructured objects may also be used as function parameters, but should be kept 1030 as simple as possible: a single level of unquoted shorthand properties. Deeper 1031 levels of nesting and computed properties may not be used in parameter 1032 destructuring. Specify any default values in the left-hand-side of the 1033 destructured parameter (<code>{str = 'some default'} = {}</code>, rather than <code class="badcode">{str} = {str: 'some default'}</code>), and if a destructured 1034 object is itself optional, it must default to <code>{}</code>. The JSDoc for the 1035 destructured parameter may be given any name (the name is unused but is required 1036 by the compiler).</p> 1037 1038 <p>Example:</p> 1039 1040 <pre><code class="language-js prettyprint">/** 1041 * @param {string} ordinary 1042 * @param {{num: (number|undefined), str: (string|undefined)}=} param1 1043 * num: The number of times to do something. 1044 * str: A string to do stuff to. 1045 */ 1046 function destructured(ordinary, {num, str = 'some default'} = {}) 1047 </code></pre> 1048 1049 <p>Illegal:</p> 1050 1051 <pre><code class="language-js prettyprint badcode">/** @param {{x: {num: (number|undefined), str: (string|undefined)}}} param1 */ 1052 function nestedTooDeeply({x: {num, str}}) {}; 1053 /** @param {{num: (number|undefined), str: (string|undefined)}=} param1 */ 1054 function nonShorthandProperty({num: a, str: b} = {}) {}; 1055 /** @param {{a: number, b: number}} param1 */ 1056 function computedKey({a, b, [a + b]: c}) {}; 1057 /** @param {{a: number, b: string}=} param1 */ 1058 function nontrivialDefault({a, b} = {a: 2, b: 4}) {}; 1059 </code></pre> 1060 1061 <p>Destructuring may also be used for <code>goog.require</code> statements, and in this case 1062 must not be wrapped: the entire statement occupies one line, regardless of how 1063 long it is (see <a href="#file-goog-require">??</a>).</p> 1064 1065 <h4 id="features-objects-enums">5.3.8 Enums</h4> 1066 1067 <p>Enumerations are defined by adding the <code>@enum</code> annotation to an object literal. 1068 Additional properties may not be added to an enum after it is defined. Enums 1069 must be constant, and all enum values must be deeply immutable.</p> 1070 1071 <pre><code class="language-js prettyprint">/** 1072 * Supported temperature scales. 1073 * @enum {string} 1074 */ 1075 const TemperatureScale = { 1076 CELSIUS: 'celsius', 1077 FAHRENHEIT: 'fahrenheit', 1078 }; 1079 1080 /** 1081 * An enum with two options. 1082 * @enum {number} 1083 */ 1084 const Option = { 1085 /** The option used shall have been the first. */ 1086 FIRST_OPTION: 1, 1087 /** The second among two options. */ 1088 SECOND_OPTION: 2, 1089 }; 1090 </code></pre> 1091 1092 <h3 id="features-classes">5.4 Classes</h3> 1093 1094 <h4 id="features-classes-constructors">5.4.1 Constructors</h4> 1095 1096 <p>Constructors are optional for concrete classes. Subclass constructors must call 1097 <code>super()</code> before setting any fields or otherwise accessing <code>this</code>. Interfaces 1098 must not define a constructor.</p> 1099 1100 <h4 id="features-classes-fields">5.4.2 Fields</h4> 1101 1102 <p>Set all of a concrete object’s fields (i.e. all properties other than methods) 1103 in the constructor. Annotate fields that are never reassigned with <code>@const</code> 1104 (these need not be deeply immutable). Private fields must be annotated with 1105 <code>@private</code> and their names must end with a trailing underscore. Fields are never 1106 set on a concrete class' <code>prototype</code>.</p> 1107 1108 <p>Example:</p> 1109 1110 <pre><code class="language-js prettyprint">class Foo { 1111 constructor() { 1112 /** @private @const {!Bar} */ 1113 this.bar_ = computeBar(); 1114 } 1115 } 1116 </code></pre> 1117 1118 <p>Tip: Properties should never be added to or removed from an instance after the 1119 constructor is finished, since it significantly hinders VMs’ ability to 1120 optimize. If necessary, fields that are initialized later should be explicitly 1121 set to <code>undefined</code> in the constructor to prevent later shape changes. Adding 1122 <code>@struct</code> to an object will check that undeclared properties are not 1123 added/accessed. Classes have this added by default.</p> 1124 1125 <h4 id="features-classes-computed-properties">5.4.3 Computed properties</h4> 1126 1127 1128 1129 <p>Computed properties may only be used in classes when the property is a 1130 symbol. Dict-style properties (that is, quoted or computed non-symbol keys, as 1131 defined in <a href="#features-objects-mixing-keys">??</a>) are not allowed. A 1132 <code>[Symbol.iterator]</code> method should be defined for any classes that are logically 1133 iterable. Beyond this, <code>Symbol</code> should be used sparingly.</p> 1134 1135 <p>Tip: be careful of using any other built-in symbols (e.g., <code>Symbol.isConcatSpreadable</code>) as they are not polyfilled by the compiler and will therefore not work in older browsers.</p> 1136 1137 <h4 id="features-classes-static-methods">5.4.4 Static methods</h4> 1138 1139 1140 1141 <p>Where it does not interfere with readability, prefer module-local functions over 1142 private static methods.</p> 1143 1144 <p>Static methods should only be called on the base class itself. Static methods 1145 should not be called on variables containing a dynamic instance that may be 1146 either the constructor or a subclass constructor (and must be defined with 1147 <code>@nocollapse</code> if this is done), and must not be called directly on a subclass 1148 that doesn’t define the method itself.</p> 1149 1150 <p>Illegal:</p> 1151 1152 <pre><code class="language-js prettyprint badcode">class Base { /** @nocollapse */ static foo() {} } 1153 class Sub extends Base {} 1154 function callFoo(cls) { cls.foo(); } // discouraged: don't call static methods dynamically 1155 Sub.foo(); // illegal: don't call static methods on subclasses that don't define it themselves 1156 </code></pre> 1157 1158 <h4 id="features-classes-old-style">5.4.5 Old-style class declarations</h4> 1159 1160 <p>While ES6 classes are preferred, there are cases where ES6 classes may not be 1161 feasible. For example:</p> 1162 1163 <ol> 1164 <li><p>If there exist or will exist subclasses, including frameworks that create 1165 subclasses, that cannot be immediately changed to use ES6 class syntax. If 1166 such a class were to use ES6 syntax, all downstream subclasses not using ES6 1167 class syntax would need to be modified.</p></li> 1168 <li><p>Frameworks that require a known <code>this</code> value before calling the superclass 1169 constructor, since constructors with ES6 super classes do not have 1170 access to the instance <code>this</code> value until the call to <code>super</code> returns.</p></li> 1171 </ol> 1172 1173 <p>In all other ways the style guide still applies to this code: <code>let</code>, <code>const</code>, 1174 default parameters, rest, and arrow functions should all be used when 1175 appropriate.</p> 1176 1177 <p><code>goog.defineClass</code> allows for a class-like definition similar to ES6 class 1178 syntax:</p> 1179 1180 <pre><code class="language-javascript">let C = goog.defineClass(S, { 1181 /** 1182 * @param {string} value 1183 */ 1184 constructor(value) { 1185 S.call(this, 2); 1186 /** @const */ 1187 this.prop = value; 1188 }, 1189 1190 /** 1191 * @param {string} param 1192 * @return {number} 1193 */ 1194 method(param) { 1195 return 0; 1196 }, 1197 }); 1198 </code></pre> 1199 1200 <p>Alternatively, while <code>goog.defineClass</code> should be preferred for all new code, 1201 more traditional syntax is also allowed.</p> 1202 1203 <pre><code class="language-javascript">/** 1204 * @constructor @extends {S} 1205 * @param {string} value 1206 */ 1207 function C(value) { 1208 S.call(this, 2); 1209 /** @const */ 1210 this.prop = value; 1211 } 1212 goog.inherits(C, S); 1213 1214 /** 1215 * @param {string} param 1216 * @return {number} 1217 */ 1218 C.prototype.method = function(param) { 1219 return 0; 1220 }; 1221 </code></pre> 1222 1223 <p>Per-instance properties should be defined in the constructor after the call to the super class constructor, if there is a super class. Methods should be defined on the prototype of the constructor.</p> 1224 1225 <p>Defining constructor prototype hierarchies correctly is harder than it first appears! For that reason, it is best to use <code>goog.inherits</code> from <a href="http://code.google.com/closure/library/">the Closure Library </a>.</p> 1226 1227 <h4 id="features-classes-prototypes">5.4.6 Do not manipulate <code>prototype</code>s directly</h4> 1228 1229 <p>The <code>class</code> keyword allows clearer and more readable class definitions than 1230 defining <code>prototype</code> properties. Ordinary implementation code has no business 1231 manipulating these objects, though they are still useful for defining <code>@record</code> 1232 interfaces and classes as defined in <a href="#features-classes-old-style">??</a>. Mixins 1233 and modifying the prototypes of builtin objects are 1234 explicitly forbidden.</p> 1235 1236 <p><strong>Exception</strong>: Framework code (such as Polymer, or Angular) may need to use <code>prototype</code>s, and should not 1237 resort to even-worse workarounds to avoid doing so.</p> 1238 1239 <p><strong>Exception</strong>: Defining fields in interfaces (see <a href="#features-classes-interfaces">??</a>).</p> 1240 1241 <h4 id="features-classes-getters-and-setters">5.4.7 Getters and Setters</h4> 1242 1243 <p>Do not use <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get">JavaScript getter and setter properties</a>. They are potentially 1244 surprising and difficult to reason about, and have limited support in the 1245 compiler. Provide ordinary methods instead.</p> 1246 1247 <p><strong>Exception</strong>: when working with data binding frameworks (such as Angular and 1248 Polymer), getters and setters may be used sparingly. Note, however, that 1249 compiler support is limited. When they are used, they must be defined either 1250 with <code>get foo()</code> and <code>set foo(value)</code> in the class or object literal, or if that 1251 is not possible, with <code>Object.defineProperties</code>. Do not use 1252 <code>Object.defineProperty</code>, which interferes with property renaming. Getters 1253 <strong>must not</strong> change observable state.</p> 1254 1255 <p>Illegal:</p> 1256 1257 <pre><code class="language-js prettyprint badcode">class Foo { 1258 get next() { return this.nextId++; } 1259 } 1260 </code></pre> 1261 1262 <h4 id="features-classes-overriding-tostring">5.4.8 Overriding toString</h4> 1263 1264 <p>The <code>toString</code> method may be overridden, but must always succeed and never have 1265 visible side effects.</p> 1266 1267 <p>Tip: Beware, in particular, of calling other methods from toString, since 1268 exceptional conditions could lead to infinite loops.</p> 1269 1270 <h4 id="features-classes-interfaces">5.4.9 Interfaces</h4> 1271 1272 <p>Interfaces may be declared with <code>@interface</code> or <code>@record</code>. Interfaces declared 1273 with <code>@record</code> can be explicitly (i.e. via <code>@implements</code>) or implicitly 1274 implemented by a class or object literal.</p> 1275 1276 <p>All non-static method bodies on an interface must be empty blocks. Fields must 1277 be defined after the interface body as stubs on the <code>prototype</code>.</p> 1278 1279 <p>Example:</p> 1280 1281 <pre><code class="language-js prettyprint">/** 1282 * Something that can frobnicate. 1283 * @record 1284 */ 1285 class Frobnicator { 1286 /** 1287 * Performs the frobnication according to the given strategy. 1288 * @param {!FrobnicationStrategy} strategy 1289 */ 1290 frobnicate(strategy) {} 1291 } 1292 1293 /** @type {number} The number of attempts before giving up. */ 1294 Frobnicator.prototype.attempts; 1295 </code></pre> 1296 1297 <h3 id="features-functions">5.5 Functions</h3> 1298 1299 <h4 id="features-functions-top-level-functions">5.5.1 Top-level functions</h4> 1300 1301 <p>Exported functions may be defined directly on the <code>exports</code> object, or else 1302 declared locally and exported separately. Non-exported functions are encouraged 1303 and should not be declared <code>@private</code>.</p> 1304 1305 <p>Examples:</p> 1306 1307 <pre><code class="language-js prettyprint">/** @return {number} */ 1308 function helperFunction() { 1309 return 42; 1310 } 1311 /** @return {number} */ 1312 function exportedFunction() { 1313 return helperFunction() * 2; 1314 } 1315 /** 1316 * @param {string} arg 1317 * @return {number} 1318 */ 1319 function anotherExportedFunction(arg) { 1320 return helperFunction() / arg.length; 1321 } 1322 /** @const */ 1323 exports = {exportedFunction, anotherExportedFunction}; 1324 </code></pre> 1325 1326 <pre><code class="language-js prettyprint">/** @param {string} arg */ 1327 exports.foo = (arg) => { 1328 // do some stuff ... 1329 }; 1330 </code></pre> 1331 1332 <h4 id="features-functions-nested-functions">5.5.2 Nested functions and closures</h4> 1333 1334 <p>Functions may contain nested function definitions. If it is useful to give the 1335 function a name, it should be assigned to a local <code>const</code>.</p> 1336 1337 <h4 id="features-functions-arrow-functions">5.5.3 Arrow functions</h4> 1338 1339 <p>Arrow functions provide a concise syntax and fix a number of difficulties with 1340 <code>this</code>. Prefer arrow functions over the <code>function</code> keyword, particularly for 1341 nested functions (but see <a href="#features-objects-method-shorthand">??</a>).</p> 1342 1343 <p>Prefer using arrow functions over <code>f.bind(this)</code>, and especially over 1344 <code>goog.bind(f, this)</code>. Avoid writing <code>const self = this</code>. Arrow functions are 1345 particularly useful for callbacks, which sometimes pass unexpected additional 1346 arguments.</p> 1347 1348 <p>The right-hand side of the arrow may be a single expression or a block. 1349 Parentheses around the arguments are optional if there is only a single 1350 non-destructured argument.</p> 1351 1352 <p>Tip: It is a good practice to use parentheses even for single-argument arrows, 1353 since the code may still parse reasonably (but incorrectly) if the parentheses 1354 are forgotten when an additional argument is added.</p> 1355 1356 <h4 id="features-functions-generators">5.5.4 Generators</h4> 1357 1358 <p>Generators enable a number of useful abstractions and may be used as needed.</p> 1359 1360 <p>When defining generator functions, attach the <code>*</code> to the <code>function</code> keyword when 1361 present, and separate it with a space from the name of the function. When using 1362 delegating yields, attach the <code>*</code> to the <code>yield</code> keyword.</p> 1363 1364 <p>Example:</p> 1365 1366 <pre><code class="language-js prettyprint">/** @return {!Iterator<number>} */ 1367 function* gen1() { 1368 yield 42; 1369 } 1370 1371 /** @return {!Iterator<number>} */ 1372 const gen2 = function*() { 1373 yield* gen1(); 1374 } 1375 1376 class SomeClass { 1377 /** @return {!Iterator<number>} */ 1378 * gen() { 1379 yield 42; 1380 } 1381 } 1382 </code></pre> 1383 1384 <h4 id="features-functions-parameters">5.5.5 Parameters</h4> 1385 1386 <p>Function parameters must be typed with JSDoc annotations in the JSDoc preceding 1387 the function’s definition, except in the case of same-signature <code>@override</code>s, 1388 where all types are omitted.</p> 1389 1390 <p>Parameter types <em>may</em> be specified inline, immediately before the parameter name 1391 (as in <code>(/** number */ foo, /** string */ bar) => foo + bar</code>). Inline and 1392 <code>@param</code> type annotations <em>must not</em> be mixed in the same function definition.</p> 1393 1394 <h5 id="features-functions-default-parameters">5.5.5.1 Default parameters</h5> 1395 1396 <p>Optional parameters are permitted using the equals operator in the parameter 1397 list. Optional parameters must include spaces on both sides of the equals 1398 operator, be named exactly like required parameters (i.e., not prefixed with 1399 <code>opt_</code>), use the <code>=</code> suffix in their JSDoc type, come after required parameters, 1400 and not use initializers that produce observable side effects. All optional 1401 parameters must have a default value in the function declaration, even if that 1402 value is <code>undefined</code>.</p> 1403 1404 <p>Example:</p> 1405 1406 <pre><code class="language-js prettyprint">/** 1407 * @param {string} required This parameter is always needed. 1408 * @param {string=} optional This parameter can be omitted. 1409 * @param {!Node=} node Another optional parameter. 1410 */ 1411 function maybeDoSomething(required, optional = '', node = undefined) {} 1412 </code></pre> 1413 1414 <p>Use default parameters sparingly. Prefer destructuring (as in 1415 <a href="#features-objects-destructuring">??</a>) to create readable APIs when there 1416 are more than a small handful of optional parameters that do not have a natural 1417 order.</p> 1418 1419 <p>Note: Unlike Python's default parameters, it is okay to use initializers that 1420 return new mutable objects (such as <code>{}</code> or <code>[]</code>) because the initializer is 1421 evaluated each time the default value is used, so a single object won't be 1422 shared across invocations.</p> 1423 1424 <p>Tip: While arbitrary expressions including function calls may be used as 1425 initializers, these should be kept as simple as possible. Avoid initializers 1426 that expose shared mutable state, as that can easily introduce unintended 1427 coupling between function calls.</p> 1428 1429 <h5 id="features-functions-rest-parameters">5.5.5.2 Rest parameters</h5> 1430 1431 <p>Use a <em>rest</em> parameter instead of accessing <code>arguments</code>. Rest parameters are 1432 typed with a <code>...</code> prefix in their JSDoc. The rest parameter must be the last 1433 parameter in the list. There is no space between the <code>...</code> and the parameter 1434 name. Do not name the rest parameter <code>var_args</code>. Never name a local variable or 1435 parameter <code>arguments</code>, which confusingly shadows the built-in name.</p> 1436 1437 <p>Example:</p> 1438 1439 <pre><code class="language-js prettyprint">/** 1440 * @param {!Array<string>} array This is an ordinary parameter. 1441 * @param {...number} numbers The remainder of arguments are all numbers. 1442 */ 1443 function variadic(array, ...numbers) {} 1444 </code></pre> 1445 1446 <h4 id="features-functions-returns">5.5.6 Returns</h4> 1447 1448 <p>Function return types must be specified in the JSDoc directly above the function 1449 definition, except in the case of same-signature <code>@override</code>s where all types 1450 are omitted.</p> 1451 1452 <h4 id="features-functions-generics">5.5.7 Generics</h4> 1453 1454 <p>Declare generic functions and methods when necessary with <code>@template TYPE</code> in 1455 the JSDoc above the class definition.</p> 1456 1457 <h4 id="features-functions-spread-operator">5.5.8 Spread operator</h4> 1458 1459 <p>Function calls may use the spread operator (<code>...</code>). Prefer the spread operator 1460 to <code>Function.prototype.apply</code> when an array or iterable is unpacked into 1461 multiple parameters of a variadic function. There is no space after the <code>...</code>.</p> 1462 1463 <p>Example:</p> 1464 1465 <pre><code class="language-js prettyprint">function myFunction(...elements) {} 1466 myFunction(...array, ...iterable, ...generator()); 1467 </code></pre> 1468 1469 <h3 id="features-string-literals">5.6 String literals</h3> 1470 1471 <h4 id="features-strings-use-single-quotes">5.6.1 Use single quotes</h4> 1472 1473 <p>Ordinary string literals are delimited with single quotes (<code>'</code>), rather than 1474 double quotes (<code>"</code>).</p> 1475 1476 <p>Tip: if a string contains a single quote character, consider using a template 1477 string to avoid having to escape the quote.</p> 1478 1479 <p>Ordinary string literals may not span multiple lines.</p> 1480 1481 <h4 id="features-strings-template-strings">5.6.2 Template strings</h4> 1482 1483 <p>Use template strings (delimited with <code>`</code>) over complex string 1484 concatenation, particularly if multiple string literals are involved. Template 1485 strings may span multiple lines.</p> 1486 1487 <p>If a template string spans multiple lines, it does not need to follow the 1488 indentation of the enclosing block, though it may if the added whitespace does 1489 not matter.</p> 1490 1491 <p>Example:</p> 1492 1493 <pre><code class="language-js prettyprint">function arithmetic(a, b) { 1494 return `Here is a table of arithmetic operations: 1495 ${a} + ${b} = ${a + b} 1496 ${a} - ${b} = ${a - b} 1497 ${a} * ${b} = ${a * b} 1498 ${a} / ${b} = ${a / b}`; 1499 } 1500 </code></pre> 1501 1502 <h4 id="features-strings-no-line-continuations">5.6.3 No line continuations</h4> 1503 1504 <p>Do not use <em>line continuations</em> (that is, ending a line inside a string literal 1505 with a backslash) in either ordinary or template string literals. Even though 1506 ES5 allows this, it can lead to tricky errors if any trailing whitespace comes 1507 after the slash, and is less obvious to readers.</p> 1508 1509 <p>Illegal:</p> 1510 1511 <pre><code class="language-js prettyprint badcode">const longString = 'This is a very long string that far exceeds the 80 \ 1512 column limit. It unfortunately contains long stretches of spaces due \ 1513 to how the continued lines are indented.'; 1514 </code></pre> 1515 1516 <p>Instead, write</p> 1517 1518 <pre><code class="language-js prettyprint">const longString = 'This is a very long string that far exceeds the 80 ' + 1519 'column limit. It does not contain long stretches of spaces since ' + 1520 'the concatenated strings are cleaner.'; 1521 </code></pre> 1522 1523 <h3 id="features-number-literals">5.7 Number literals</h3> 1524 1525 <p>Numbers may be specified in decimal, hex, octal, or binary. Use exactly <code>0x</code>, 1526 <code>0o</code>, and <code>0b</code> prefixes, with lowercase letters, for hex, octal, and binary, 1527 respectively. Never include a leading zero unless it is immediately followed by 1528 <code>x</code>, <code>o</code>, or <code>b</code>.</p> 1529 1530 <h3 id="features-control-structures">5.8 Control structures</h3> 1531 1532 <h4 id="features-for-loops">5.8.1 For loops</h4> 1533 1534 <p>With ES6, the language now has three different kinds of <code>for</code> loops. All may be 1535 used, though <code>for</code>-<code>of</code> loops should be preferred when possible.</p> 1536 1537 <p><code>for</code>-<code>in</code> loops may only be used on dict-style objects (see 1538 <a href="#features-objects-mixing-keys">??</a>), and should not be used to iterate over an 1539 array. <code>Object.prototype.hasOwnProperty</code> should be used in <code>for</code>-<code>in</code> loops to 1540 exclude unwanted prototype properties. Prefer <code>for</code>-<code>of</code> and <code>Object.keys</code> over 1541 <code>for</code>-<code>in</code> when possible.</p> 1542 1543 <h4 id="features-exceptions">5.8.2 Exceptions</h4> 1544 1545 <p>Exceptions are an important part of the language and should be used whenever 1546 exceptional cases occur. Always throw <code>Error</code>s or subclasses of <code>Error</code>: never 1547 throw string literals or other objects. Always use <code>new</code> when constructing an 1548 <code>Error</code>.</p> 1549 1550 <p>Custom exceptions provide a great way to convey additional error information 1551 from functions. They should be defined and used wherever the native <code>Error</code> 1552 type is insufficient.</p> 1553 1554 <p>Prefer throwing exceptions over ad-hoc error-handling approaches (such as 1555 passing an error container reference type, or returning an object with an error 1556 property).</p> 1557 1558 <h5 id="features-empty-catch-blocks">5.8.2.1 Empty catch blocks</h5> 1559 1560 <p>It is very rarely correct to do nothing in response to a caught exception. When 1561 it truly is appropriate to take no action whatsoever in a catch block, the 1562 reason this is justified is explained in a comment.</p> 1563 1564 <pre><code class="language-js prettyprint">try { 1565 return handleNumericResponse(response); 1566 } catch (ok) { 1567 // it's not numeric; that's fine, just continue 1568 } 1569 return handleTextResponse(response); 1570 </code></pre> 1571 1572 <p>Illegal:</p> 1573 1574 <pre><code class="language-js prettyprint badcode"> try { 1575 shouldFail(); 1576 fail('expected an error'); 1577 } 1578 catch (expected) {} 1579 </code></pre> 1580 1581 <p>Tip: Unlike in some other languages, patterns like the above simply don’t work 1582 since this will catch the error thrown by <code>fail</code>. Use <code>assertThrows()</code> instead.</p> 1583 1584 <h4 id="features-switch-statements">5.8.3 Switch statements</h4> 1585 1586 <p>Terminology Note: Inside the braces of a switch block are one or more statement groups. Each statement group consists of one or more switch labels (either <code>case FOO:</code> or <code>default:</code>), followed by one or more statements.</p> 1587 1588 <h5 id="features-switch-fall-through">5.8.3.1 Fall-through: commented</h5> 1589 1590 <p>Within a switch block, each statement group either terminates abruptly (with a 1591 <code>break</code>, <code>return</code> or <code>throw</code>n exception), or is marked with a comment to 1592 indicate that execution will or might continue into the next statement 1593 group. Any comment that communicates the idea of fall-through is sufficient 1594 (typically <code>// fall through</code>). This special comment is not required in the last 1595 statement group of the switch block.</p> 1596 1597 <p>Example:</p> 1598 1599 <pre><code class="language-js prettyprint">switch (input) { 1600 case 1: 1601 case 2: 1602 prepareOneOrTwo(); 1603 // fall through 1604 case 3: 1605 handleOneTwoOrThree(); 1606 break; 1607 default: 1608 handleLargeNumber(input); 1609 } 1610 </code></pre> 1611 1612 <h5 id="features-switch-default-case">5.8.3.2 The <code>default</code> case is present</h5> 1613 1614 <p>Each switch statement includes a <code>default</code> statement group, even if it contains 1615 no code.</p> 1616 1617 <h3 id="features-this">5.9 this</h3> 1618 1619 <p>Only use <code>this</code> in class constructors and methods, or in arrow functions defined 1620 within class constructors and methods. Any other uses of <code>this</code> must have an 1621 explicit <code>@this</code> declared in the immediately-enclosing function’s JSDoc.</p> 1622 1623 <p>Never use <code>this</code> to refer to the global object, the context of an <code>eval</code>, the 1624 target of an event, or unnecessarily <code>call()</code>ed or <code>apply()</code>ed functions.</p> 1625 1626 <h3 id="disallowed-features">5.10 Disallowed features</h3> 1627 1628 <h4 id="disallowed-features-with">5.10.1 with</h4> 1629 1630 <p>Do not use the <code>with</code> keyword. It makes your code harder to understand and has 1631 been banned in strict mode since ES5.</p> 1632 1633 <h4 id="disallowed-features-dynamic-code-evaluation">5.10.2 Dynamic code evaluation</h4> 1634 1635 <p>Do not use <code>eval</code> or the <code>Function(...string)</code> constructor (except for code 1636 loaders). These features are potentially dangerous and simply do not work in 1637 CSP environments.</p> 1638 1639 <h4 id="disallowed-features-automatic-semicolon-insertion">5.10.3 Automatic semicolon insertion</h4> 1640 1641 <p>Always terminate statements with semicolons (except function and class 1642 declarations, as noted above).</p> 1643 1644 <h4 id="disallowed-features-non-standard-features">5.10.4 Non-standard features</h4> 1645 1646 <p>Do not use non-standard features. This includes old features that have been 1647 removed (e.g., <code>WeakMap.clear</code>), new features that are not yet standardized 1648 (e.g., the current TC39 working draft, proposals at any stage, or proposed but 1649 not-yet-complete web standards), or proprietary features that are only 1650 implemented in some browsers. Use only features defined in the current ECMA-262 1651 or WHATWG standards. (Note that projects writing against specific APIs, such as 1652 Chrome extensions or Node.js, can obviously use those APIs). Non-standard 1653 language “extensions” (such as those provided by some external transpilers) are 1654 forbidden.</p> 1655 1656 <h4 id="disallowed-features-wrapper-objects">5.10.5 Wrapper objects for primitive types</h4> 1657 1658 <p>Never use <code>new</code> on the primitive object wrappers (<code>Boolean</code>, <code>Number</code>, <code>String</code>, 1659 <code>Symbol</code>), nor include them in type annotations.</p> 1660 1661 <p>Illegal:</p> 1662 1663 <pre><code class="language-js prettyprint badcode">const /** Boolean */ x = new Boolean(false); 1664 if (x) alert(typeof x); // alerts 'object' - WAT? 1665 </code></pre> 1666 1667 <p>The wrappers may be called as functions for coercing (which is preferred over 1668 using <code>+</code> or concatenating the empty string) or creating symbols.</p> 1669 1670 <p>Example:</p> 1671 1672 <pre><code class="language-js prettyprint">const /** boolean */ x = Boolean(0); 1673 if (!x) alert(typeof x); // alerts 'boolean', as expected 1674 </code></pre> 1675 1676 <h4 id="disallowed-features-modifying-builtin-objects">5.10.6 Modifying builtin objects</h4> 1677 1678 <p>Never modify builtin types, either by adding methods to their constructors or to 1679 their prototypes. Avoid depending on libraries that do this. Note that the 1680 JSCompiler’s runtime library will provide standards-compliant polyfills where 1681 possible; nothing else may modify builtin objects.</p> 1682 1683 <p>Do not add symbols to the global object unless absolutely necessary 1684 (e.g. required by a third-party API).</p> 1685 1686 <h2 id="naming">6 Naming</h2> 1687 1688 <h3 id="naming-rules-common-to-all-identifiers">6.1 Rules common to all identifiers</h3> 1689 1690 <p>Identifiers use only ASCII letters and digits, and, in a small number of cases 1691 noted below, underscores and very rarely (when required by frameworks like 1692 Angular) dollar signs.</p> 1693 1694 <p>Give as descriptive a name as possible, within reason. Do not worry about saving 1695 horizontal space as it is far more important to make your code immediately 1696 understandable by a new reader. Do not use abbreviations that are ambiguous or 1697 unfamiliar to readers outside your project, and do not abbreviate by deleting 1698 letters within a word.</p> 1699 1700 <pre><code class="language-js prettyprint">priceCountReader // No abbreviation. 1701 numErrors // "num" is a widespread convention. 1702 numDnsConnections // Most people know what "DNS" stands for. 1703 </code></pre> 1704 1705 <p>Illegal:</p> 1706 1707 <pre><code class="language-js prettyprint badcode">n // Meaningless. 1708 nErr // Ambiguous abbreviation. 1709 nCompConns // Ambiguous abbreviation. 1710 wgcConnections // Only your group knows what this stands for. 1711 pcReader // Lots of things can be abbreviated "pc". 1712 cstmrId // Deletes internal letters. 1713 kSecondsPerDay // Do not use Hungarian notation. 1714 </code></pre> 1715 1716 <h3 id="naming-rules-by-identifier-type">6.2 Rules by identifier type</h3> 1717 1718 <h4 id="naming-package-names">6.2.1 Package names</h4> 1719 1720 <p>Package names are all <code>lowerCamelCase</code>. For example, 1721 <code>my.exampleCode.deepSpace</code>, but not <code class="badcode">my.examplecode.deepspace</code> or <code class="badcode">my.example_code.deep_space</code>.</p> 1722 1723 <h4 id="naming-class-names">6.2.2 Class names</h4> 1724 1725 <p>Class, interface, record, and typedef names are written in <code>UpperCamelCase</code>. 1726 Unexported classes are simply locals: they are not marked <code>@private</code> and 1727 therefore are not named with a trailing underscore.</p> 1728 1729 <p>Type names are typically nouns or noun phrases. For example, <code>Request</code>, 1730 <code>ImmutableList</code>, or <code>VisibilityMode</code>. Additionally, interface names may 1731 sometimes be adjectives or adjective phrases instead (for example, <code>Readable</code>).</p> 1732 1733 <h4 id="naming-method-names">6.2.3 Method names</h4> 1734 1735 <p>Method names are written in <code>lowerCamelCase</code>. Private methods’ names must end 1736 with a trailing underscore.</p> 1737 1738 <p>Method names are typically verbs or verb phrases. For example, <code>sendMessage</code> or 1739 <code>stop_</code>. Getter and setter methods for properties are never required, but if 1740 they are used they should be named <code>getFoo</code> (or optionally <code>isFoo</code> or <code>hasFoo</code> 1741 for booleans), or <code>setFoo(value)</code> for setters.</p> 1742 1743 <p>Underscores may also appear in JsUnit test method names to separate logical 1744 components of the name. One typical pattern is <code>test<MethodUnderTest>_<state></code>, 1745 for example <code>testPop_emptyStack</code>. There is no One Correct Way to name test 1746 methods.</p> 1747 1748 <h4 id="naming-enum-names">6.2.4 Enum names</h4> 1749 1750 <p>Enum names are written in <code>UpperCamelCase</code>, similar to classes, and should 1751 generally be singular nouns. Individual items within the enum are named in 1752 <code>CONSTANT_CASE</code>.</p> 1753 1754 <h4 id="naming-constant-names">6.2.5 Constant names</h4> 1755 1756 <p>Constant names use <code>CONSTANT_CASE</code>: all uppercase letters, with words separated 1757 by underscores. There is no reason for a constant to be named with a trailing 1758 underscore, since private static properties can be replaced by (implicitly 1759 private) module locals.</p> 1760 1761 <h5 id="naming-definition-of-constant">6.2.5.1 Definition of “constant”</h5> 1762 1763 <p>Every constant is a <code>@const</code> static property or a module-local <code>const</code> 1764 declaration, but not all <code>@const</code> static properties and module-local <code>const</code>s 1765 are constants. Before choosing constant case, consider whether the field really 1766 feels like a <em>deeply immutable</em> constant. For example, if any of that instance's 1767 observable state can change, it is almost certainly not a constant. Merely 1768 intending to never mutate the object is generally not enough.</p> 1769 1770 <p>Examples:</p> 1771 1772 <pre><code class="language-js prettyprint">// Constants 1773 const NUMBER = 5; 1774 /** @const */ exports.NAMES = ImmutableList.of('Ed', 'Ann'); 1775 /** @enum */ exports.SomeEnum = { ENUM_CONSTANT: 'value' }; 1776 1777 // Not constants 1778 let letVariable = 'non-const'; 1779 class MyClass { constructor() { /** @const */ this.nonStatic = 'non-static'; } }; 1780 /** @type {string} */ MyClass.staticButMutable = 'not @const, can be reassigned'; 1781 const /** Set<String> */ mutableCollection = new Set(); 1782 const /** ImmutableSet<SomeMutableType> */ mutableElements = ImmutableSet.of(mutable); 1783 const Foo = goog.require('my.Foo'); // mirrors imported name 1784 const logger = log.getLogger('loggers.are.not.immutable'); 1785 </code></pre> 1786 1787 <p>Constants’ names are typically nouns or noun phrases.</p> 1788 1789 <h5 id="naming-local-aliases">6.2.5.1 Local aliases</h5> 1790 1791 <p>Local aliases should be used whenever they improve readability over 1792 fully-qualified names. Follow the same rules as <code>goog.require</code>s 1793 (<a href="#file-goog-require">??</a>), maintaining the last part of the aliased name. 1794 Aliases may also be used within functions. Aliases must be <code>const</code>.</p> 1795 1796 <p>Examples:</p> 1797 1798 <pre><code class="language-js prettyprint">const staticHelper = importedNamespace.staticHelper; 1799 const CONSTANT_NAME = ImportedClass.CONSTANT_NAME; 1800 const {assert, assertInstanceof} = asserts; 1801 </code></pre> 1802 1803 <h4 id="naming-non-constant-field-names">6.2.6 Non-constant field names</h4> 1804 1805 <p>Non-constant field names (static or otherwise) are written in <code>lowerCamelCase</code>, 1806 with a trailing underscore for private fields.</p> 1807 1808 <p>These names are typically nouns or noun phrases. For example, <code>computedValues</code> 1809 or <code>index_</code>.</p> 1810 1811 <h4 id="naming-parameter-names">6.2.7 Parameter names</h4> 1812 1813 <p>Parameter names are written in <code>lowerCamelCase</code>. Note that this applies even if 1814 the parameter expects a constructor.</p> 1815 1816 <p>One-character parameter names should not be used in public methods.</p> 1817 1818 <p><strong>Exception</strong>: When required by a third-party framework, parameter names may 1819 begin with a <code>$</code>. This exception does not apply to any other identifiers 1820 (e.g. local variables or properties).</p> 1821 1822 <h4 id="naming-local-variable-names">6.2.8 Local variable names</h4> 1823 1824 <p>Local variable names are written in <code>lowerCamelCase</code>, except for module-local 1825 (top-level) constants, as described above. Constants in function scopes are 1826 still named in <code>lowerCamelCase</code>. Note that lowerCamelCase applies even if the 1827 variable holds a constructor.</p> 1828 1829 <h4 id="naming-template-parameter-names">6.2.9 Template parameter names</h4> 1830 1831 <p>Template parameter names should be concise, single-word or single-letter 1832 identifiers, and must be all-caps, such as <code>TYPE</code> or <code>THIS</code>.</p> 1833 1834 <h3 id="naming-camel-case-defined">6.3 Camel case: defined</h3> 1835 1836 <p>Sometimes there is more than one reasonable way to convert an English phrase 1837 into camel case, such as when acronyms or unusual constructs like <q>IPv6</q> or 1838 <q>iOS</q> are present. To improve predictability, Google Style specifies the 1839 following (nearly) deterministic scheme.</p> 1840 1841 <p>Beginning with the prose form of the name:</p> 1842 1843 <ol> 1844 <li>Convert the phrase to plain ASCII and remove any apostrophes. For example, 1845 <q>Müller's algorithm</q> might become <q>Muellers algorithm</q>.</li> 1846 <li>Divide this result into words, splitting on spaces and any remaining 1847 punctuation (typically hyphens). 1848 <ol> 1849 <li>Recommended: if any word already has a conventional camel case 1850 appearance in common usage, split this into its constituent parts (e.g., 1851 <q>AdWords</q> becomes <q>ad words</q>). Note that a word such as <q>iOS</q> is not 1852 really in camel case per se; it defies any convention, so this 1853 recommendation does not apply.</li> 1854 </ol></li> 1855 <li>Now lowercase everything (including acronyms), then uppercase only the first 1856 character of: 1857 <ol> 1858 <li>… each word, to yield upper camel case, or</li> 1859 <li>… each word except the first, to yield lower camel case</li> 1860 </ol></li> 1861 <li>Finally, join all the words into a single identifier.</li> 1862 </ol> 1863 1864 <p>Note that the casing of the original words is almost entirely disregarded.</p> 1865 1866 <p>Examples:</p> 1867 1868 <table> 1869 <thead> 1870 <tr> 1871 <th style="text-align: center">Prose form</th> 1872 <th style="text-align: center">Correct</th> 1873 <th style="text-align: center">Incorrect</th> 1874 </tr> 1875 </thead> 1876 1877 <tbody> 1878 <tr> 1879 <td style="text-align: center"><q>XML HTTP request</q></td> 1880 <td style="text-align: center">XmlHttpRequest</td> 1881 <td style="text-align: center">XMLHTTPRequest</td> 1882 </tr> 1883 <tr> 1884 <td style="text-align: center"><q>new customer ID</q></td> 1885 <td style="text-align: center">newCustomerId</td> 1886 <td style="text-align: center">newCustomerID</td> 1887 </tr> 1888 <tr> 1889 <td style="text-align: center"><q>inner stopwatch</q></td> 1890 <td style="text-align: center">innerStopwatch</td> 1891 <td style="text-align: center">innerStopWatch</td> 1892 </tr> 1893 <tr> 1894 <td style="text-align: center"><q>supports IPv6 on iOS?</q></td> 1895 <td style="text-align: center">supportsIpv6OnIos</td> 1896 <td style="text-align: center">supportsIPv6OnIOS</td> 1897 </tr> 1898 <tr> 1899 <td style="text-align: center"><q>YouTube importer</q></td> 1900 <td style="text-align: center">YouTubeImporter</td> 1901 <td style="text-align: center">YoutubeImporter*</td> 1902 </tr> 1903 </tbody> 1904 </table> 1905 1906 <p>*Acceptable, but not recommended.</p> 1907 1908 <p>Note: Some words are ambiguously hyphenated in the English language: for example <q>nonempty</q> and <q>non-empty</q> are both correct, so the method names checkNonempty and checkNonEmpty are likewise both correct.</p> 1909 1910 <h2 id="jsdoc">7 JSDoc</h2> 1911 1912 <p><a href="https://developers.google.com/closure/compiler/docs/js-for-compiler">JSDoc</a> is used on all classes, fields, and methods.</p> 1913 1914 <h3 id="jsdoc-general-form">7.1 General form</h3> 1915 1916 <p>The basic formatting of JSDoc blocks is as seen in this example:</p> 1917 1918 <pre><code class="language-js prettyprint">/** 1919 * Multiple lines of JSDoc text are written here, 1920 * wrapped normally. 1921 * @param {number} arg A number to do something to. 1922 */ 1923 function doSomething(arg) { … } 1924 </code></pre> 1925 1926 <p>or in this single-line example:</p> 1927 1928 <pre><code class="language-js prettyprint">/** @const @private {!Foo} A short bit of JSDoc. */ 1929 this.foo_ = foo; 1930 </code></pre> 1931 1932 <p>If a single-line comment overflows into multiple lines, it must use the 1933 multi-line style with <code>/**</code> and <code>*/</code> on their own lines.</p> 1934 1935 <p>Many tools extract metadata from JSDoc comments to perform code validation and 1936 optimization. As such, these comments <strong>must</strong> be well-formed.</p> 1937 1938 <h3 id="jsdoc-markdown">7.2 Markdown</h3> 1939 1940 <p>JSDoc is written in Markdown, though it may include HTML when necessary.</p> 1941 1942 <p>Note that tools that automatically extract JSDoc (e.g. <a href="https://github.com/jleyba/js-dossier">JsDossier</a>) will often 1943 ignore plain text formatting, so if you did this:</p> 1944 1945 <pre><code class="language-js prettyprint badcode">/** 1946 * Computes weight based on three factors: 1947 * items sent 1948 * items received 1949 * last timestamp 1950 */ 1951 </code></pre> 1952 1953 <p>it would come out like this:</p> 1954 1955 <pre><code>Computes weight based on three factors: items sent items received last timestamp 1956 </code></pre> 1957 1958 <p>Instead, write a Markdown list:</p> 1959 1960 <pre><code class="language-js prettyprint">/** 1961 * Computes weight based on three factors: 1962 * - items sent 1963 * - items received 1964 * - last timestamp 1965 */ 1966 </code></pre> 1967 1968 <h3 id="jsdoc-tags">7.3 JSDoc tags</h3> 1969 1970 <p>Google style allows a subset of JSDoc tags. See 1971 <a href="#appendices-jsdoc-tag-reference">??</a> for the complete list. Most tags must 1972 occupy their own line, with the tag at the beginning of the line.</p> 1973 1974 <p>Illegal:</p> 1975 1976 <pre><code class="language-js prettyprint badcode">/** 1977 * The "param" tag must occupy its own line and may not be combined. 1978 * @param {number} left @param {number} right 1979 */ 1980 function add(left, right) { ... } 1981 </code></pre> 1982 1983 <p>Simple tags that do not require any additional data (such as <code>@private</code>, 1984 <code>@const</code>, <code>@final</code>, <code>@export</code>) may be combined onto the same line, along with an 1985 optional type when appropriate.</p> 1986 1987 <pre><code class="language-js prettyprint">/** 1988 * Place more complex annotations (like "implements" and "template") 1989 * on their own lines. Multiple simple tags (like "export" and "final") 1990 * may be combined in one line. 1991 * @export @final 1992 * @implements {Iterable<TYPE>} 1993 * @template TYPE 1994 */ 1995 class MyClass { 1996 /** 1997 * @param {!ObjType} obj Some object. 1998 * @param {number=} num An optional number. 1999 */ 2000 constructor(obj, num = 42) { 2001 /** @private @const {!Array<!ObjType|number>} */ 2002 this.data_ = [obj, num]; 2003 } 2004 } 2005 </code></pre> 2006 2007 <p>There is no hard rule for when to combine tags, or in which order, but be 2008 consistent.</p> 2009 2010 <p>For general information about annotating types in JavaScript see 2011 <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler">Annotating JavaScript for the Closure Compiler</a> and <a href="https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System">Types in the Closure Type 2012 System</a>.</p> 2013 2014 <h3 id="jsdoc-line-wrapping">7.4 Line wrapping</h3> 2015 2016 <p>Line-wrapped block tags are indented four spaces. Wrapped description text may 2017 be lined up with the description on previous lines, but this horizontal 2018 alignment is discouraged.</p> 2019 2020 <pre><code class="language-js prettyprint">/** 2021 * Illustrates line wrapping for long param/return descriptions. 2022 * @param {string} foo This is a param with a description too long to fit in 2023 * one line. 2024 * @return {number} This returns something that has a description too long to 2025 * fit in one line. 2026 */ 2027 exports.method = function(foo) { 2028 return 5; 2029 }; 2030 </code></pre> 2031 2032 <p>Do not indent when wrapping a <code>@fileoverview</code> description.</p> 2033 2034 <h3 id="jsdoc-top-file-level-comments">7.5 Top/file-level comments</h3> 2035 2036 <p>A file may have a top-level file overview. A copyright notice , author information, and 2037 default <a href="#jsdoc-visibility-annotations">visibility level</a> are optional. File overviews are generally recommended whenever a 2038 file consists of more than a single class definition. The top level comment is 2039 designed to orient readers unfamiliar with the code to what is in this file. If 2040 present, it may provide a description of the file's contents and any 2041 dependencies or compatibility information. Wrapped lines are not indented.</p> 2042 2043 <p>Example:</p> 2044 2045 <pre><code class="language-js prettyprint">/** 2046 * @fileoverview Description of file, its uses and information 2047 * about its dependencies. 2048 * @package 2049 */ 2050 </code></pre> 2051 2052 <h3 id="jsdoc-class-comments">7.6 Class comments</h3> 2053 2054 <p>Classes, interfaces and records must be documented with a description and any 2055 template parameters, implemented interfaces, visibility, or other appropriate 2056 tags. The class description should provide the reader with enough information to 2057 know how and when to use the class, as well as any additional considerations 2058 necessary to correctly use the class. Textual descriptions may be omitted on the 2059 constructor. <code>@constructor</code> and <code>@extends</code> annotations are not used with the 2060 <code>class</code> keyword unless the class is being used to declare an <code>@interface</code> or 2061 it extends a generic class.</p> 2062 2063 <pre><code class="language-js prettyprint">/** 2064 * A fancier event target that does cool things. 2065 * @implements {Iterable<string>} 2066 */ 2067 class MyFancyTarget extends EventTarget { 2068 /** 2069 * @param {string} arg1 An argument that makes this more interesting. 2070 * @param {!Array<number>} arg2 List of numbers to be processed. 2071 */ 2072 constructor(arg1, arg2) { 2073 // ... 2074 } 2075 }; 2076 2077 /** 2078 * Records are also helpful. 2079 * @extends {Iterator<TYPE>} 2080 * @record 2081 * @template TYPE 2082 */ 2083 class Listable { 2084 /** @return {TYPE} The next item in line to be returned. */ 2085 next() {} 2086 } 2087 </code></pre> 2088 2089 <h3 id="jsdoc-enum-and-typedef-comments">7.7 Enum and typedef comments</h3> 2090 2091 <p>Enums and typedefs must be documented. Public enums and typedefs must have a 2092 non-empty description. Individual enum items may be documented with a JSDoc 2093 comment on the preceding line.</p> 2094 2095 <pre><code class="language-js prettyprint">/** 2096 * A useful type union, which is reused often. 2097 * @typedef {!Bandersnatch|!BandersnatchType} 2098 */ 2099 let CoolUnionType; 2100 2101 2102 /** 2103 * Types of bandersnatches. 2104 * @enum {string} 2105 */ 2106 const BandersnatchType = { 2107 /** This kind is really frumious. */ 2108 FRUMIOUS: 'frumious', 2109 /** The less-frumious kind. */ 2110 MANXOME: 'manxome', 2111 }; 2112 </code></pre> 2113 2114 <p>Typedefs are useful for defining short record types, or aliases for unions, 2115 complex functions, or generic types. 2116 Typedefs should be avoided for record types with many fields, since they do not 2117 allow documenting individual fields, nor using templates or recursive 2118 references. 2119 For large record types, prefer <code>@record</code>.</p> 2120 2121 <h3 id="jsdoc-method-and-function-comments">7.8 Method and function comments</h3> 2122 2123 <p>Parameter and return types must be documented. The <code>this</code> type should be 2124 documented when necessary. Method, parameter, and return descriptions (but not 2125 types) may be omitted if they are obvious from the rest of the method’s JSDoc or 2126 from its signature. Method descriptions should start with a sentence written in 2127 the third person declarative voice. If a method overrides a superclass method, 2128 it must include an <code>@override</code> annotation. Overridden methods must include all 2129 <code>@param</code> and <code>@return</code> annotations if any types are refined, but should omit 2130 them if the types are all the same.</p> 2131 2132 <pre><code class="language-js prettyprint">/** This is a class. */ 2133 class SomeClass extends SomeBaseClass { 2134 /** 2135 * Operates on an instance of MyClass and returns something. 2136 * @param {!MyClass} obj An object that for some reason needs detailed 2137 * explanation that spans multiple lines. 2138 * @param {!OtherClass} obviousOtherClass 2139 * @return {boolean} Whether something occurred. 2140 */ 2141 someMethod(obj, obviousOtherClass) { ... } 2142 2143 /** @override */ 2144 overriddenMethod(param) { ... } 2145 } 2146 2147 /** 2148 * Demonstrates how top-level functions follow the same rules. This one 2149 * makes an array. 2150 * @param {TYPE} arg 2151 * @return {!Array<TYPE>} 2152 * @template TYPE 2153 */ 2154 function makeArray(arg) { ... } 2155 </code></pre> 2156 2157 2158 2159 <p>Anonymous functions do not require JSDoc, though parameter types may be specified inline if the automatic type inference is insufficient.</p> 2160 2161 <pre><code class="language-js prettyprint">promise.then( 2162 (/** !Array<number|string> */ items) => { 2163 doSomethingWith(items); 2164 return /** @type {string} */ (items[0]); 2165 }); 2166 </code></pre> 2167 2168 <h3 id="jsdoc-property-comments">7.9 Property comments</h3> 2169 2170 <p>Property types must be documented. The description may be omitted for private 2171 properties, if name and type provide enough documentation for understanding the 2172 code.</p> 2173 2174 <p>Publicly exported constants are commented the same way as properties. Explicit 2175 types may be omitted for <code>@const</code> properties initialized from an expression with 2176 an obviously known type.</p> 2177 2178 <p>Tip: A <code>@const</code> property’s type can be considered “obviously known” if it is 2179 assigned directly from a constructor parameter with a declared type, or directly 2180 from a function call with a declared return type. Non-const properties and 2181 properties assigned from more complex expressions should have their types 2182 declared explicitly.</p> 2183 2184 <pre><code class="language-js prettyprint">/** My class. */ 2185 class MyClass { 2186 /** @param {string=} someString */ 2187 constructor(someString = 'default string') { 2188 /** @private @const */ 2189 this.someString_ = someString; 2190 2191 /** @private @const {!OtherType} */ 2192 this.someOtherThing_ = functionThatReturnsAThing(); 2193 2194 /** 2195 * Maximum number of things per pane. 2196 * @type {number} 2197 */ 2198 this.someProperty = 4; 2199 } 2200 } 2201 2202 /** 2203 * The number of times we'll try before giving up. 2204 * @const 2205 */ 2206 MyClass.RETRY_COUNT = 33; 2207 </code></pre> 2208 2209 <h3 id="jsdoc-type-annotations">7.10 Type annotations</h3> 2210 2211 <p>Type annotations are found on <code>@param</code>, <code>@return</code>, <code>@this</code>, and <code>@type</code> tags, 2212 and optionally on <code>@const</code>, <code>@export</code>, and any visibility tags. Type 2213 annotations attached to JSDoc tags must always be enclosed in braces.</p> 2214 2215 <h4 id="jsdoc-nullability">7.10.1 Nullability</h4> 2216 2217 <p>The type system defines modifiers <code>!</code> and <code>?</code> for non-null and nullable, 2218 respectively. Primitive types (<code>undefined</code>, <code>string</code>, <code>number</code>, <code>boolean</code>, 2219 <code>symbol</code>, and <code>function(...): ...</code>) and record literals (<code>{foo: string, bar: 2220 number}</code>) are non-null by default. Do not add an explicit <code>!</code> to these types. 2221 Object types (<code>Array</code>, <code>Element</code>, <code>MyClass</code>, etc) are nullable by default, but 2222 cannot be immediately distinguished from a name that is <code>@typedef</code>’d to a 2223 non-null-by-default type. As such, all types except primitives and record 2224 literals must be annotated explicitly with either <code>?</code> or <code>!</code> to indicate whether 2225 they are nullable or not.</p> 2226 2227 <h4 id="jsdoc-type-casts">7.10.2 Type Casts</h4> 2228 2229 <p>In cases where type checking doesn't accurately infer the type of an expression, 2230 it is possible to tighten the type by adding a type annotation comment and 2231 enclosing the expression in parentheses. Note that the parentheses are required.</p> 2232 2233 <pre><code class="language-js prettyprint">/** @type {number} */ (x) 2234 </code></pre> 2235 2236 <h4 id="jsdoc-template-parameter-types">7.10.3 Template Parameter Types</h4> 2237 2238 <p>Always specify template parameters. This way compiler can do a better job and it 2239 makes it easier for readers to understand what code does.</p> 2240 2241 <p>Bad:</p> 2242 2243 <pre><code class="language-js prettyprint badcode">const /** !Object */ users = {}; 2244 const /** !Array */ books = []; 2245 const /** !Promise */ response = ...; 2246 </code></pre> 2247 2248 <p>Good:</p> 2249 2250 <pre><code class="language-js prettyprint">const /** !Object<string, !User> */ users = {}; 2251 const /** !Array<string> */ books = []; 2252 const /** !Promise<!Response> */ response = ...; 2253 2254 const /** !Promise<undefined> */ thisPromiseReturnsNothingButParameterIsStillUseful = ...; 2255 const /** !Object<string, *> */ mapOfEverything = {}; 2256 </code></pre> 2257 2258 <p>Cases when template parameters should not be used:</p> 2259 2260 <ul> 2261 <li><code>Object</code> is used for type hierarchy and not as map-like structure.</li> 2262 </ul> 2263 2264 <h3 id="jsdoc-visibility-annotations">7.11 Visibility annotations</h3> 2265 2266 <p>Visibility annotations (<code>@private</code>, <code>@package</code>, <code>@protected</code>) may be specified 2267 in a <code>@fileoverview</code> block, or on any exported symbol or property. Do not 2268 specify visibility for local variables, whether within a function or at the top 2269 level of a module. All <code>@private</code> names must end with an underscore.</p> 2270 2271 <h2 id="policies">8 Policies</h2> 2272 2273 <h3 id="policies-be-consistent">8.1 Issues unspecified by Google Style: Be Consistent!</h3> 2274 2275 <p>For any style question that isn't settled definitively by this specification, 2276 prefer to do what the other code in the same file is already doing. If that 2277 doesn't resolve the question, consider emulating the other files in the same 2278 package.</p> 2279 2280 <h3 id="policies-compiler-warnings">8.2 Compiler warnings</h3> 2281 2282 <h4 id="policies-use-a-standard-warning-set">8.2.1 Use a standard warning set</h4> 2283 2284 <p> 2285 As far as possible projects should use <code>--warning_level=VERBOSE</code>. 2286 </p> 2287 2288 <h4 id="policies-how-to-handle-a-warning">8.2.2 How to handle a warning</h4> 2289 2290 <p>Before doing anything, make sure you understand exactly what the warning is 2291 telling you. If you're not positive why a warning is appearing, ask for help 2292 .</p> 2293 2294 <p>Once you understand the warning, attempt the following solutions in order:</p> 2295 2296 <ol> 2297 <li><strong>First, fix it or work around it.</strong> Make a strong attempt to actually 2298 address the warning, or find another way to accomplish the task that avoids 2299 the situation entirely.</li> 2300 <li><strong>Otherwise, determine if it's a false alarm.</strong> If you are convinced that 2301 the warning is invalid and that the code is actually safe and correct, add a 2302 comment to convince the reader of this fact and apply the <code>@suppress</code> 2303 annotation.</li> 2304 <li><strong>Otherwise, leave a TODO comment.</strong> This is a <strong>last resort</strong>. If you do 2305 this, <strong>do not suppress the warning.</strong> The warning should be visible until 2306 it can be taken care of properly.</li> 2307 </ol> 2308 2309 <h4 id="policies-suppress-a-warning-at-the-narrowest-reasonable-scope">8.2.3 Suppress a warning at the narrowest reasonable scope</h4> 2310 2311 <p>Warnings are suppressed at the narrowest reasonable scope, usually that of a single local variable or very small method. Often a variable or method is extracted for that reason alone.</p> 2312 2313 <p>Example</p> 2314 2315 <pre><code class="language-js prettyprint">/** @suppress {uselessCode} Unrecognized 'use asm' declaration */ 2316 function fn() { 2317 'use asm'; 2318 return 0; 2319 } 2320 </code></pre> 2321 2322 <p>Even a large number of suppressions in a class is still better than blinding the 2323 entire class to this type of warning.</p> 2324 2325 <h3 id="policies-deprecation">8.3 Deprecation</h3> 2326 2327 <p>Mark deprecated methods, classes or interfaces with <code>@deprecated</code> annotations. A 2328 deprecation comment must include simple, clear directions for people to fix 2329 their call sites.</p> 2330 2331 <h3 id="policies-code-not-in-google-style">8.4 Code not in Google Style</h3> 2332 2333 <p>You will occasionally encounter files in your codebase that are not in proper 2334 Google Style. These may have come from an acquisition, or may have been written 2335 before Google Style took a position on some issue, or may be in non-Google Style 2336 for any other reason.</p> 2337 2338 <h4 id="policies-reformatting-existing-code">8.4.1 Reformatting existing code</h4> 2339 2340 <p>When updating the style of existing code, follow these guidelines.</p> 2341 2342 <ol> 2343 <li>It is not required to change all existing code to meet current style 2344 guidelines. Reformatting existing code is a trade-off between code churn 2345 and consistency. Style rules evolve over time and these kinds of tweaks to 2346 maintain compliance would create unnecessary churn. However, if significant 2347 changes are being made to a file it is expected that the file will be in 2348 Google Style.</li> 2349 <li>Be careful not to allow opportunistic style fixes to muddle the focus of a 2350 CL. If you find yourself making a lot of style changes that aren’t critical 2351 to the central focus of a CL, promote those changes to a separate CL.</li> 2352 </ol> 2353 2354 <h4 id="policies-newly-added-code-use-google-style">8.4.2 Newly added code: use Google Style</h4> 2355 2356 <p>Brand new files use Google Style, regardless of the style choices of other files 2357 in the same package.</p> 2358 2359 <p>When adding new code to a file that is not in Google Style, reformatting the 2360 existing code first is recommended, subject to the advice in 2361 <a href="#policies-reformatting-existing-code">??</a>.</p> 2362 2363 <p>If this reformatting is not done, then new code should be as consistent as 2364 possible with existing code in the same file, but must not violate the style 2365 guide.</p> 2366 2367 <h3 id="policies-local-style-rules">8.5 Local style rules</h3> 2368 2369 <p>Teams and projects may adopt additional style rules beyond those in this 2370 document, but must accept that cleanup changes may not abide by these additional 2371 rules, and must not block such cleanup changes due to violating any additional 2372 rules. Beware of excessive rules which serve no purpose. The style guide does 2373 not seek to define style in every possible scenario and neither should you.</p> 2374 2375 <h3 id="policies-generated-code-mostly-exempt">8.6 Generated code: mostly exempt</h3> 2376 2377 <p>Source code generated by the build process is not required to be in Google 2378 Style. However, any generated identifiers that will be referenced from 2379 hand-written source code must follow the naming requirements. As a special 2380 exception, such identifiers are allowed to contain underscores, which may help 2381 to avoid conflicts with hand-written identifiers.</p> 2382 2383 <h2 id="appendices">9 Appendices</h2> 2384 2385 <h3 id="appendices-jsdoc-tag-reference">9.1 JSDoc tag reference</h3> 2386 2387 <p>JSDoc serves multiple purposes in JavaScript. In addition to being used to 2388 generate documentation it is also used to control tooling. The best known are 2389 the Closure Compiler type annotations.</p> 2390 2391 <h4 id="appendices-type-annotations">9.1.1 Type annotations and other Closure Compiler annotations</h4> 2392 2393 <p>Documentation for JSDoc used by the Closure Compiler is described in 2394 <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler">Annotating JavaScript for the Closure Compiler</a> and <a href="https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System">Types in the Closure Type 2395 System</a>.</p> 2396 2397 <h4 id="appendices-documentation-annotations">9.1.2 Documentation annotations</h4> 2398 2399 <p>In addition to the JSDoc described in <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler">Annotating JavaScript for the Closure 2400 Compiler</a> the following tags are common and well supported by various 2401 documentation generations tools (such as <a href="https://github.com/jleyba/js-dossier">JsDossier</a>) for purely documentation 2402 purposes. 2403 <table> 2404 <thead> 2405 <tr> 2406 <th>Tag 2407 </th><th>Template & Examples 2408 </th><th>Description 2409 </th></tr></thead><tbody> 2410 <tr> 2411 <td><code>@author</code> or <code>@owner</code> 2412 </td><td><code>@author username (a] google.com (First Last)</code> 2413 <p><em>For example:</em> 2414 </p><pre class="prettyprint lang-js"> 2415 /** 2416 * @fileoverview Utilities for handling textareas. 2417 * @author <a href="mailto:kuth (a] google.com">kuth (a] google.com</a> (Uthur Pendragon) 2418 */ 2419 </pre> 2420 </td><td>Document the author of a file or the owner of a test, generally only 2421 used in the <code>@fileoverview</code> comment. The <code>@owner</code> tag is used by the 2422 unit test dashboard to determine who owns the test results. 2423 <p>Not recommended. 2424 </p></td></tr><tr> 2425 <td><code>@bug</code> 2426 </td><td><code>@bug bugnumber</code> 2427 <p><em>For example:</em> 2428 </p><pre class="prettyprint lang-js"> 2429 /** @bug 1234567 */ 2430 function testSomething() { 2431 // … 2432 } 2433 2434 <p>/** 2435 * @bug 1234568 2436 * @bug 1234569 2437 */ 2438 function testTwoBugs() { 2439 // … 2440 } 2441 </p></pre> 2442 </td><td>Indicates what bugs the given test function regression tests. 2443 <p>Multiple bugs should each have their own <code>@bug</code> line, to make 2444 searching for regression tests as easy as possible. 2445 </p></td></tr><tr> 2446 <td><code>@code</code> 2447 </td><td><code>{@code ...}</code> 2448 <p><em>For example:</em> 2449 </p><pre class="prettyprint lang-js"> 2450 /** 2451 * Moves to the next position in the selection. 2452 * Throws {@code goog.iter.StopIteration} when it 2453 * passes the end of the range. 2454 * @return {!Node} The node at the next position. 2455 */ 2456 goog.dom.RangeIterator.prototype.next = function() { 2457 // … 2458 }; 2459 </pre> 2460 </td><td>Indicates that a term in a JSDoc description is code so it may be 2461 correctly formatted in generated documentation. 2462 </td></tr><tr> 2463 <td><code>@see</code> 2464 </td><td><code>@see Link</code> 2465 <p><em>For example:</em> 2466 </p><pre class="prettyprint lang-js"> 2467 /** 2468 * Adds a single item, recklessly. 2469 * @see #addSafely 2470 * @see goog.Collect 2471 * @see goog.RecklessAdder#add 2472 */ 2473 </pre> 2474 </td><td>Reference a lookup to another class function or method. 2475 </td></tr><tr> 2476 <td><code>@supported</code> 2477 </td><td><code>@supported Description</code> 2478 <p><em>For example:</em> 2479 </p><pre class="prettyprint lang-js"> 2480 /** 2481 * @fileoverview Event Manager 2482 * Provides an abstracted interface to the 2483 * browsers' event systems. 2484 * @supported IE10+, Chrome, Safari 2485 */ 2486 </pre> 2487 </td><td>Used in a fileoverview to indicate what browsers are supported by 2488 the file. 2489 </td></tr><tr> 2490 <td><code>@desc</code> 2491 </td><td><code>@desc Message description</code> 2492 <p><em>For example:</em> 2493 </p><pre class="prettyprint lang-js"> 2494 /** @desc Notifying a user that their account has been created. */ 2495 exports.MSG_ACCOUNT_CREATED = goog.getMsg( 2496 'Your account has been successfully created.'); 2497 </pre> 2498 </td></tr></tbody></table></p> 2499 2500 <p>You may also see other types of JSDoc annotations in third-party code. These 2501 annotations appear in the <a href="http://code.google.com/p/jsdoc-toolkit/wiki/TagReference">JSDoc Toolkit Tag Reference</a> but are not considered 2502 part of valid Google style.</p> 2503 2504 <h4 id="appendices-framework-specific-annotations">9.1.3 Framework specific annotations</h4> 2505 2506 <p>The following annotations are specific to a particular framework. 2507 <table> 2508 <thead> 2509 <tr> 2510 <th>Framework 2511 </th><th>Tag 2512 </th><th>Documentation 2513 </th></tr></thead><tbody> 2514 <tr> 2515 <td>Angular 1 2516 </td><td><code>@ngInject</code> 2517 </td></tr><tr> 2518 <td>Polymer 2519 </td><td><code>@polymerBehavior</code> 2520 </td><td> 2521 2522 <a href="https://github.com/google/closure-compiler/wiki/Polymer-Pass">https://github.com/google/closure-compiler/wiki/Polymer-Pass</a> 2523 2524 </td></tr></tbody></table></p> 2525 2526 <h4 id="appendices-notes-about-standard-closure-compiler-annotations">9.1.4 Notes about standard Closure Compiler annotations</h4> 2527 2528 <p>The following tags used to be standard but are now deprecated. 2529 <table> 2530 <thead> 2531 <tr> 2532 <th>Tag 2533 </th><th>Template & Examples 2534 </th><th>Description 2535 </th></tr></thead><tbody> 2536 <tr> 2537 <td><code>@expose</code> 2538 </td><td><code>@expose</code> 2539 </td><td><strong>Deprecated. Do not use. Use <code>@export</code> and/or <code>@nocollapse</code> 2540 instead.</strong> 2541 </td></tr><tr> 2542 <td><code>@inheritDoc</code> 2543 </td><td><code>@inheritDoc</code> 2544 </td><td><strong>Deprecated. Do not use. Use <code>@override</code> instead.</strong> 2545 </td></tr></tbody></table></p> 2546 2547 <h3 id="appendices-commonly-misunderstood-style-rules">9.2 Commonly misunderstood style rules</h3> 2548 2549 <p>Here is a collection of lesser-known or commonly misunderstood facts about 2550 Google Style for JavaScript. (The following are true statements; this is not a 2551 list of <q>myths.</q>)</p> 2552 2553 <ul> 2554 <li>Neither a copyright statement nor <code>@author</code> credit is required in a source 2555 file. (Neither is explicitly recommended, either.)</li> 2556 <li>Aside from the constructor coming first 2557 (<a href="#features-classes-constructors">??</a>), there is no <q>hard and fast</q> rule 2558 governing how to order the members of a class (<a href="#features-classes">??</a>).</li> 2559 <li>Empty blocks can usually be represented concisely as <code>{}</code>, as detailed in 2560 (<a href="#formatting-empty-blocks">??</a>).</li> 2561 <li>The prime directive of line-wrapping is: prefer to break at a higher 2562 syntactic level (<a href="#formatting-where-to-break">??</a>).</li> 2563 <li>Non-ASCII characters are allowed in string literals, comments and Javadoc, 2564 and in fact are recommended when they make the code easier to read than the 2565 equivalent Unicode escape would (<a href="#non-ascii-characters">??</a>).</li> 2566 </ul> 2567 2568 <h3 id="appendices-style-related-tools">9.3 Style-related tools</h3> 2569 2570 <p>The following tools exist to support various aspects of Google Style.</p> 2571 2572 <h4 id="appendices-tools-closure-compiler">9.3.1 Closure Compiler</h4> 2573 2574 <p>This program performs type checking and other checks, 2575 optimizations and other transformations (such as ECMAScript 6 to ECMAScript 5 2576 code lowering).</p> 2577 2578 <h4 id="appendices-clang-format">9.3.2 <code>clang-format</code></h4> 2579 2580 <p>This program reformats 2581 JavaScript source code into Google Style, and also follows a number of 2582 non-required but frequently readability-enhancing formatting practices.</p> 2583 2584 <p><code>clang-format</code> is not required. Authors are allowed to change its output, and 2585 reviewers are allowed to ask for such changes; disputes are worked out in the 2586 usual way. However, subtrees may choose to opt in to such enforcement locally.</p> 2587 2588 <h4 id="appendices-closure-compiler-linter">9.3.3 Closure compiler linter</h4> 2589 2590 <p>This program checks for a 2591 variety of missteps and anti-patterns. 2592 </p> 2593 2594 <h4 id="appendices-conformance-framework">9.3.4 Conformance framework</h4> 2595 2596 <p>The JS Conformance Framework is a tool that is part of the Closure Compiler that 2597 provides developers a simple means to specify a set of additional checks to be 2598 run against their code base above the standard checks. Conformance checks can, 2599 for example, forbid access to a certain property, or calls to a certain 2600 function, or missing type information (unknowns).</p> 2601 2602 <p>These rules are commonly used to enforce critical restrictions (such as defining 2603 globals, which could break the codebase) and security patterns (such as using 2604 <code>eval</code> or assigning to <code>innerHTML</code>), or more loosely to improve code quality.</p> 2605 2606 <p>For additional information see the official documentation for the 2607 <a href="https://github.com/google/closure-compiler/wiki/JS-Conformance-Framework">JS Conformance Framework</a>.</p> 2608 2609 <h3 id="appendices-legacy-exceptions">9.4 Exceptions for legacy platforms</h3> 2610 2611 <h4 id="appendices-legacy-exceptions-overview">9.4.1 Overview</h4> 2612 2613 <p>This section describes exceptions and additional rules to be followed when 2614 modern ECMAScript 6 syntax is not available to the code authors. Exceptions to 2615 the recommended style are required when ECMAScript 6 syntax is not possible and 2616 are outlined here:</p> 2617 2618 <ul> 2619 <li>Use of <code>var</code> declarations is allowed</li> 2620 <li>Use of <code>arguments</code> is allowed</li> 2621 <li>Optional parameters without default values are allowed</li> 2622 </ul> 2623 2624 <h4 id="appendices-legacy-exceptions-var">9.4.2 Use <code>var</code></h4> 2625 2626 <h5 id="appendices-legacy-exceptions-var-scope">9.4.2.1 <code>var</code> declarations are NOT block-scoped</h5> 2627 2628 <p><code>var</code> declarations are scoped to the beginning of the nearest enclosing 2629 function, script or module, which can cause unexpected behavior, especially with 2630 function closures that reference <code>var</code> declarations inside of loops. The 2631 following code gives an example:</p> 2632 2633 <pre><code class="language-js prettyprint badcode">for (var i = 0; i < 3; ++i) { 2634 var iteration = i; 2635 setTimeout(function() { console.log(iteration); }, i*1000); 2636 } 2637 2638 // logs 2, 2, 2 -- NOT 0, 1, 2 2639 // because `iteration` is function-scoped, not local to the loop. 2640 2641 </code></pre> 2642 2643 <h5 id="appendices-legacy-exceptions-var-declare">9.4.2.2 Declare variables as close as possible to first use</h5> 2644 2645 <p>Even though <code>var</code> declarations are scoped to the beginning of the enclosing 2646 function, <code>var</code> declarations should be as close as possible to their first use, 2647 for readability purposes. However, do not put a <code>var</code> declaration inside a block 2648 if that variable is referenced outside the block. For example:</p> 2649 2650 <pre><code class="language-js prettyprint">function sillyFunction() { 2651 var count = 0; 2652 for (var x in y) { 2653 // "count" could be declared here, but don't do that. 2654 count++; 2655 } 2656 console.log(count + ' items in y'); 2657 } 2658 </code></pre> 2659 2660 <h5 id="appendices-legacy-exceptions-var-const">9.4.2.3 Use @const for constants variables</h5> 2661 2662 <p>For global declarations where the <code>const</code> keyword would be used, if it were 2663 available, annotate the <code>var</code> declaration with @const instead (this is optional 2664 for local variables).</p> 2665 2666 <h4 id="appendices-legacy-exceptions-function">9.4.3 Do not use block scoped functions declarations</h4> 2667 2668 <p>Do <strong>not</strong> do this:</p> 2669 2670 <pre><code class="language-js prettyprint badcode">if (x) { 2671 function foo() {} 2672 } 2673 </code></pre> 2674 2675 <p>While most JavaScript VMs implemented before ECMAScript 6 support function 2676 declarations within blocks it was not standardized. Implementations were 2677 inconsistent with each other and with the now-standard ECMAScript 6 behavior for 2678 block scoped function declaration. ECMAScript 5 and prior only allow for 2679 function declarations in the root statement list of a script or function and 2680 explicitly ban them in block scopes in strict mode.</p> 2681 2682 <p>To get consistent behavior, instead use a <code>var</code> initialized with a function 2683 expression to define a function within a block:</p> 2684 2685 <pre><code class="language-js prettyprint">if (x) { 2686 var foo = function() {}; 2687 } 2688 </code></pre> 2689 2690 <h4 id="appendices-legacy-exceptions-goog-provide">9.4.4 Dependency management with <code>goog.provide</code>/<code>goog.require</code></h4> 2691 2692 <p><strong><code>goog.provide</code> is deprecated. All new files should use <code>goog.module</code>, even in 2693 projects with existing <code>goog.provide</code> usage. The following rules are for 2694 pre-existing goog.provide files, only.</strong></p> 2695 2696 <h5 id="appendices-legacy-exceptions-goog-provide-summary">9.4.4.1 Summary</h5> 2697 2698 <ul> 2699 <li>Place all <code>goog.provide</code>s first, <code>goog.require</code>s second. Separate provides 2700 from requires with an empty line.</li> 2701 <li>Sort the entries alphabetically (uppercase first).</li> 2702 <li>Don't wrap <code>goog.provide</code> and <code>goog.require</code> statements. Exceed 80 columns 2703 if necessary.</li> 2704 <li>Only provide top-level symbols.</li> 2705 </ul> 2706 2707 <p>As of Oct 2016, <strong><code>goog.provide</code>/<code>goog.require</code> dependency management is 2708 deprecated</strong>. All new files, even in projects using <code>goog.provide</code> for older 2709 files, should use 2710 <a href="#source-file-structure"><code>goog.module</code></a>.</p> 2711 2712 <p><code>goog.provide</code> statements should be grouped together and placed first. All 2713 <code>goog.require</code> statements should follow. The two lists should be separated with 2714 an empty line.</p> 2715 2716 <p>Similar to import statements in other languages, <code>goog.provide</code> and 2717 <code>goog.require</code> statements should be written in a single line, even if they 2718 exceed the 80 column line length limit.</p> 2719 2720 <p>The lines should be sorted alphabetically, with uppercase letters coming first:</p> 2721 2722 <pre><code class="language-js prettyprint">goog.provide('namespace.MyClass'); 2723 goog.provide('namespace.helperFoo'); 2724 2725 goog.require('an.extremelyLongNamespace.thatSomeoneThought.wouldBeNice.andNowItIsLonger.Than80Columns'); 2726 goog.require('goog.dom'); 2727 goog.require('goog.dom.TagName'); 2728 goog.require('goog.dom.classes'); 2729 goog.require('goog.dominoes'); 2730 2731 </code></pre> 2732 2733 <p>All members defined on a class should be in the same file. Only top-level 2734 classes should be provided in a file that contains multiple members defined on 2735 the same class (e.g. enums, inner classes, etc).</p> 2736 2737 <p>Do this:</p> 2738 2739 <pre><code class="language-js prettyprint">goog.provide('namespace.MyClass'); 2740 </code></pre> 2741 2742 <p>Not this:</p> 2743 2744 <pre><code class="language-js prettyprint badcode">goog.provide('namespace.MyClass'); 2745 goog.provide('namespace.MyClass.CONSTANT'); 2746 goog.provide('namespace.MyClass.Enum'); 2747 goog.provide('namespace.MyClass.InnerClass'); 2748 goog.provide('namespace.MyClass.TypeDef'); 2749 goog.provide('namespace.MyClass.staticMethod'); 2750 </code></pre> 2751 2752 <p>Members on namespaces may also be provided:</p> 2753 2754 <pre><code class="language-js prettyprint">goog.provide('foo.bar'); 2755 goog.provide('foo.bar.CONSTANT'); 2756 goog.provide('foo.bar.method'); 2757 </code></pre> 2758 2759 <h5 id="appendices-legacy-exceptions-goog-scope">9.4.4.2 Aliasing with <code>goog.scope</code></h5> 2760 2761 <p><strong><code>goog.scope</code> is deprecated. New files should not use <code>goog.scope</code> even in 2762 projects with existing goog.scope usage.</strong></p> 2763 2764 <p><code>goog.scope</code> may be used to shorten references to namespaced symbols in 2765 code using <code>goog.provide</code>/<code>goog.require</code> dependency management.</p> 2766 2767 <p>Only one <code>goog.scope</code> invocation may be added per file. Always place it in 2768 the global scope.</p> 2769 2770 <p>The opening <code>goog.scope(function() {</code> invocation must be preceded by exactly one 2771 blank line and follow any <code>goog.provide</code> statements, <code>goog.require</code> statements, 2772 or top-level comments. The invocation must be closed on the last line in the 2773 file. Append <code>// goog.scope</code> to the closing statement of the scope. Separate the 2774 comment from the semicolon by two spaces.</p> 2775 2776 <p>Similar to C++ namespaces, do not indent under <code>goog.scope</code> declarations. 2777 Instead, continue from the 0 column.</p> 2778 2779 <p>Only make aliases for names that will not be re-assigned to another object 2780 (e.g., most constructors, enums, and namespaces). Do not do this (see below for 2781 how to alias a constructor):</p> 2782 2783 <pre><code class="language-js prettyprint badcode">goog.scope(function() { 2784 var Button = goog.ui.Button; 2785 2786 Button = function() { ... }; 2787 ... 2788 </code></pre> 2789 2790 <p>Names must be the same as the last property of the global that they are aliasing.</p> 2791 2792 <pre><code class="language-js prettyprint">goog.provide('my.module.SomeType'); 2793 2794 goog.require('goog.dom'); 2795 goog.require('goog.ui.Button'); 2796 2797 goog.scope(function() { 2798 var Button = goog.ui.Button; 2799 var dom = goog.dom; 2800 2801 // Alias new types after the constructor declaration. 2802 my.module.SomeType = function() { ... }; 2803 var SomeType = my.module.SomeType; 2804 2805 // Declare methods on the prototype as usual: 2806 SomeType.prototype.findButton = function() { 2807 // Button as aliased above. 2808 this.button = new Button(dom.getElement('my-button')); 2809 }; 2810 ... 2811 }); // goog.scope 2812 </code></pre> 2813 2814 </div> 2815 </body> 2816 </html> 2817
