0001.pdf (43516B)
1 %PDF-1.1 2 1 0 obj 3 << 4 /CreationDate (D:20210812231743) 5 /Producer (text2pdf v1.1 (\251 Phil Smith, 1996)) 6 /Title (0001 - JavaScript Styling) 7 >> 8 endobj 9 2 0 obj 10 << 11 /Type /Catalog 12 /Pages 3 0 R 13 >> 14 endobj 15 4 0 obj 16 << 17 /Type /Font 18 /Subtype /Type1 19 /Name /F1 20 /BaseFont /Courier 21 >> 22 endobj 23 5 0 obj 24 << 25 /Font << /F1 4 0 R >> 26 /ProcSet [ /PDF /Text ] 27 >> 28 endobj 29 6 0 obj 30 << 31 /Type /Page 32 /Parent 3 0 R 33 /Resources 5 0 R 34 /Contents 7 0 R 35 >> 36 endobj 37 7 0 obj 38 << 39 /Length 8 0 R 40 >> 41 stream 42 BT 43 /F1 10 Tf 44 1 0 0 1 50 802 Tm 45 12 TL 46 (Specification: 0001 Robin Bron)' 47 ( August 2018)' 48 ()' 49 ()' 50 ()' 51 ( JavaScript Styling)' 52 ()' 53 ()' 54 (This document describes a set of rules for JavaScript source code. To apply)' 55 (these rules, include the next paragraph near the beginning of the documentation)' 56 (of the project or near the beginning of the generic README file of the project:)' 57 ()' 58 ( The JavaScript source code in this project must adhere to the rules as)' 59 ( described in FINWO/SPEC0001)' 60 ()' 61 ()' 62 ()' 63 ()' 64 ()' 65 ()' 66 ()' 67 ()' 68 ()' 69 ()' 70 ()' 71 ()' 72 ()' 73 ()' 74 ()' 75 ()' 76 ()' 77 ()' 78 ()' 79 ()' 80 ()' 81 ()' 82 ()' 83 ()' 84 ()' 85 ()' 86 ()' 87 ()' 88 ()' 89 ()' 90 ()' 91 ()' 92 ()' 93 ()' 94 ()' 95 ()' 96 ()' 97 (Copyright Notice)' 98 ()' 99 ( This document is licensed under a)' 100 ( Creative Commons Attribution 4.0 International License)' 101 ()' 102 ( You should have received a copy of the license along with this work. If not,)' 103 ( see <http://creativecommons.org/licenses/by/4.0/>)' 104 ()' 105 (Bron [Page 1])' 106 ET 107 endstream 108 endobj 109 8 0 obj 110 1145 111 endobj 112 9 0 obj 113 << 114 /Type /Page 115 /Parent 3 0 R 116 /Resources 5 0 R 117 /Contents 10 0 R 118 >> 119 endobj 120 10 0 obj 121 << 122 /Length 11 0 R 123 >> 124 stream 125 BT 126 /F1 10 Tf 127 1 0 0 1 50 802 Tm 128 12 TL 129 (SPEC 0001 JavaScript Styling August 2018)' 130 ()' 131 (Table of contents)' 132 ()' 133 ( 1. Introduction ........................................................... 4)' 134 ( 1.1. Conventions ....................................................... 4)' 135 ( 2. Source file basics ..................................................... 4)' 136 ( 2.1. File name ......................................................... 4)' 137 ( 2.2. File encoding ..................................................... 4)' 138 ( 2.3. Special characters ................................................ 4)' 139 ( 2.3.1. Whitespace characters ........................................ 4)' 140 ( 2.3.2. Special escape sequences ..................................... 4)' 141 ( 2.3.3. Non-ASCII characters ......................................... 4)' 142 ( 3. Formatting ............................................................. 5)' 143 ( 3.1. Braces ............................................................ 5)' 144 ( 3.1.1. Control structures ........................................... 5)' 145 ( 3.1.2. Non-empty blocks ............................................. 5)' 146 ( 3.1.3. Empty blocks ................................................. 5)' 147 ( 3.2. Indentation ....................................................... 5)' 148 ( 3.3. String literals ................................................... 5)' 149 ( 3.4. Number literals ................................................... 6)' 150 ( 3.5. Array literals .................................................... 6)' 151 ( 3.6. Object literals ................................................... 6)' 152 ( 3.7. Functions ......................................................... 7)' 153 ( 3.7.1. Function literals ............................................ 7)' 154 ( 3.7.2. Arrow function literals ...................................... 7)' 155 ( 3.7.3. Generator functions .......................................... 7)' 156 ( 3.7.4. Parameters ................................................... 7)' 157 ( 3.7.4.1. Default parameters ...................................... 7)' 158 ( 3.7.4.2. Rest parameters ......................................... 8)' 159 ( 3.7.5. Returns ...................................................... 8)' 160 ( 3.7.6. Spread operator .............................................. 8)' 161 ( 3.8. Classes ........................................................... 8)' 162 ( 3.8.1. Constructors ................................................. 8)' 163 ( 3.8.2. Fields ....................................................... 8)' 164 ( 3.8.3. ES5 class declarations ....................................... 8)' 165 ( 3.8.4. Prototype manipulation ....................................... 9)' 166 ( 3.8.5. Getters and setters .......................................... 9)' 167 ( 3.9. This .............................................................. 9)' 168 ( 3.10. Disallowed features .............................................. 9)' 169 ( 4. Naming ................................................................ 10)' 170 ( 4.1. Rules for all identifiers ........................................ 10)' 171 ( 4.2. Rules by identifier type ......................................... 10)' 172 ( 5. JSDoc ................................................................. 10)' 173 ( 5.1. General form .................................................... 10)' 174 ( 5.2. Summary ......................................................... 10)' 175 ( 5.3. Description ..................................................... 11)' 176 ( 5.4. Tags ............................................................ 12)' 177 ( 5.4.1. JSDoc tag reference ......................................... 12)' 178 ( 5.5. Line wrapping ................................................... 13)' 179 ( 5.6. Top/file-level comments ......................................... 13)' 180 ( 5.7. Class comments .................................................. 13)' 181 ( 5.8. Enum and typedef comments ....................................... 13)' 182 ( 5.9. Method and function comments .................................... 13)' 183 ( 5.10. Property comments ............................................... 14)' 184 ( 5.11. Nullability ..................................................... 14)' 185 ( 5.12. Template parameter types ........................................ 14)' 186 ()' 187 ()' 188 (Bron [Page 2])' 189 ET 190 endstream 191 endobj 192 11 0 obj 193 4697 194 endobj 195 12 0 obj 196 << 197 /Type /Page 198 /Parent 3 0 R 199 /Resources 5 0 R 200 /Contents 13 0 R 201 >> 202 endobj 203 13 0 obj 204 << 205 /Length 14 0 R 206 >> 207 stream 208 BT 209 /F1 10 Tf 210 1 0 0 1 50 802 Tm 211 12 TL 212 (SPEC 0001 JavaScript Styling August 2018)' 213 ()' 214 ( 6. Policies .............................................................. 14)' 215 ( 6.1. Unspecified styling .............................................. 14)' 216 ( 6.2. Deprecation ...................................................... 14)' 217 ( 6.3. Code not in Finwo Style .......................................... 14)' 218 ( 6.3.1. Reformatting existing code .................................. 15)' 219 ( 6.3.2. Newly added code ............................................ 15)' 220 ( 6.4. Local style rules ................................................ 15)' 221 ( 6.5. Generated code ................................................... 15)' 222 ( 6.6. Third-party code ................................................. 15)' 223 ( 7. Informative resources ................................................. 16)' 224 ( 8. Author information .................................................... 17)' 225 ()' 226 ()' 227 ()' 228 ()' 229 ()' 230 ()' 231 ()' 232 ()' 233 ()' 234 ()' 235 ()' 236 ()' 237 ()' 238 ()' 239 ()' 240 ()' 241 ()' 242 ()' 243 ()' 244 ()' 245 ()' 246 ()' 247 ()' 248 ()' 249 ()' 250 ()' 251 ()' 252 ()' 253 ()' 254 ()' 255 ()' 256 ()' 257 ()' 258 ()' 259 ()' 260 ()' 261 ()' 262 ()' 263 ()' 264 ()' 265 ()' 266 ()' 267 ()' 268 ()' 269 ()' 270 ()' 271 (Bron [Page 3])' 272 ET 273 endstream 274 endobj 275 14 0 obj 276 1320 277 endobj 278 15 0 obj 279 << 280 /Type /Page 281 /Parent 3 0 R 282 /Resources 5 0 R 283 /Contents 16 0 R 284 >> 285 endobj 286 16 0 obj 287 << 288 /Length 17 0 R 289 >> 290 stream 291 BT 292 /F1 10 Tf 293 1 0 0 1 50 802 Tm 294 12 TL 295 (SPEC 0001 JavaScript Styling August 2018)' 296 ()' 297 (1. Introduction)' 298 ()' 299 ( This document serves as the complete definition of the coding standards for)' 300 ( source code in the JavaScript programming language as followed by finwo. A)' 301 ( JavaScript source file is described as being in "Finwo Style" if, and only)' 302 ( if, it adheres to the rules herein.)' 303 ()' 304 ( Like other programming style guides, the issues covered span not only)' 305 ( aesthetic issues of formatting, but other types of conventions or coding)' 306 ( standards as well. However, this document focuses primarily on the)' 307 ( hard-and-fast rules that we follow universally, and avoids giving advice that)' 308 ( isn't clearly enforceable \(whether by human or tool\).)' 309 ()' 310 (1.1. Conventions)' 311 ()' 312 ( The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",)' 313 ( "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this)' 314 ( document are to be interpreted as described in RFC2119 when, and only when,)' 315 ( they appear in all capitals, as shown here.)' 316 ()' 317 (2. Source file basics)' 318 ()' 319 ( 2.1. File name)' 320 ()' 321 ( File names MUST be all lowercase and may include underscores \(_\) or dashes)' 322 ( \(-\), but no additional punctuation. The extension MUST always be ".js".)' 323 ()' 324 ( 2.2. File encoding)' 325 ()' 326 ( Source files MUST always be encoded according to the UTF-8 standard \(See)' 327 ( RFC3629\).)' 328 ()' 329 ( 2.3. Special characters)' 330 ()' 331 ( 2.3.1 Whitespace characters)' 332 ()' 333 ( Aside from the line-feed character, the ASCII \(See RFC20\) horizonal)' 334 ( space character \(0x20\) is the only whitespace character that appears)' 335 ( anywhere in a source files.)' 336 ()' 337 ( 2.3.2. Special escape sequences)' 338 ()' 339 ( For any character that has a special escape sequence, that sequence)' 340 ( SHOULD be used rather than the corresponding numeric escape sequence.)' 341 ( Legacy octal escapes MUST NOT be used.)' 342 ()' 343 ( 2.3.3. Non-ASCII characters)' 344 ()' 345 ( For the remaining non-ASCII characters, either the actual Unicode)' 346 ( character or the equivalent hex or Unicode escape is used, depending)' 347 ( only on which makes the code easier to read and understand.)' 348 ()' 349 ()' 350 ()' 351 ()' 352 ()' 353 ()' 354 (Bron [Page 4])' 355 ET 356 endstream 357 endobj 358 17 0 obj 359 2436 360 endobj 361 18 0 obj 362 << 363 /Type /Page 364 /Parent 3 0 R 365 /Resources 5 0 R 366 /Contents 19 0 R 367 >> 368 endobj 369 19 0 obj 370 << 371 /Length 20 0 R 372 >> 373 stream 374 BT 375 /F1 10 Tf 376 1 0 0 1 50 802 Tm 377 12 TL 378 (SPEC 0001 JavaScript Styling August 2018)' 379 ()' 380 (3. Formatting)' 381 ()' 382 ( 3.1. Braces)' 383 ()' 384 ( 3.1.1. Control structures)' 385 ()' 386 ( Braces are REQUIRED for all control structures \(i.e. if, else, for, do,)' 387 ( while, as wel as any others\). The first statement of a non-empty block)' 388 ( MUST begin on its own line.)' 389 ()' 390 ( Control structures SHOULD omit braces and be written on a single line)' 391 ( if the both the statement and the control structure can be kept on a)' 392 ( single line without wrapping when it improves readability.)' 393 ()' 394 ( 3.1.2. Non-empty blocks)' 395 ()' 396 ( Braces follow the Kernighan and Ritchie style \("Egyptian brackets"\) for)' 397 ( non-empty blocks and block-like structures.)' 398 ()' 399 ( - No line break before the opening brace)' 400 ( - Line break after the opening brace)' 401 ( - Line break before the closing brace)' 402 ( - Line break after the closing brace if that brace terminates a)' 403 ( statement or the body of a function or class statement, or a class)' 404 ( method. Specifically, there is no line break after the brace if it is)' 405 ( followed by "else", "catch", "while", or a comma, semicolon, or)' 406 ( right-prarenthesis.)' 407 ()' 408 ( 3.1.3. Empty blocks)' 409 ()' 410 ( An empty block or block-like construct SHOULD be closed immediately)' 411 ( after it is opened, with no characters, space, or line break in)' 412 ( between, unless it is part of a multi-block statement.)' 413 ()' 414 ( 3.2. Indentation)' 415 ()' 416 ( Each time a new block or block-like construct is opened, the indent)' 417 ( increases by two spaces. When the block ends, the indent returns to the)' 418 ( previous indent level. The indent level applies to both code and comments)' 419 ( throughout the block.)' 420 ()' 421 ( 3.3. String literals)' 422 ()' 423 ( Ordinary string literals SHOULD be delimited with single quotes \('\) and)' 424 ( MUST NOT span multiple lines.)' 425 ()' 426 ( To prevent complex string concatenation, template strings \(delimited with)' 427 ( `\) SHOULD be used. Template strings \(delimted with backticks \(`\)\) MAY span)' 428 ( multiple lines in which case they SHOULD adhere the indent level of the)' 429 ( enclosing block if the whitespace does not affect functionality or)' 430 ( increases the comlexity of the code.)' 431 ()' 432 ()' 433 ()' 434 ()' 435 ()' 436 ()' 437 (Bron [Page 5])' 438 ET 439 endstream 440 endobj 441 20 0 obj 442 2557 443 endobj 444 21 0 obj 445 << 446 /Type /Page 447 /Parent 3 0 R 448 /Resources 5 0 R 449 /Contents 22 0 R 450 >> 451 endobj 452 22 0 obj 453 << 454 /Length 23 0 R 455 >> 456 stream 457 BT 458 /F1 10 Tf 459 1 0 0 1 50 802 Tm 460 12 TL 461 (SPEC 0001 JavaScript Styling August 2018)' 462 ()' 463 ( 3.4. Number literals)' 464 ()' 465 ( Numbers may be specified in decimal, hexidecimal, octal or binary. Use)' 466 ( exactly "0x", "0o" and "0b" prefixes, with lowercase characters, for hex,)' 467 ( octal and binary respectively. Never include a leading zero unless it is)' 468 ( immediately followed by "x", "o" or "b".)' 469 ()' 470 ( 3.5. Array literals)' 471 ()' 472 ( Array literals SHOULD include a trailing comma whenever there is a line)' 473 ( break between the final element and the closing bracket.)' 474 ()' 475 ( The variadic Array constructor MUST NOT be used for creating a new array,)' 476 ( unless used for allocating an empty array of a given length.)' 477 ()' 478 ( Non-numeric properties on an array other than "length" or a Symbol MUST)' 479 ( NOT be used. Use a Map or Object instead.)' 480 ()' 481 ( Array literals MAY be used on the left-hand side of an assignment to)' 482 ( perform destructuring \(such as when unpacking multiple values from a)' 483 ( single array or iterable\). A final "rest" element MAY be included \(with no)' 484 ( space between the "..." and the variable name\).)' 485 ()' 486 ( Destructuring MAY also be used for function parameters \(note that a)' 487 ( parameter name is required but ignored\). Always specify "[]" as the)' 488 ( default value if a destructured array parameter is optional, and provide)' 489 ( default values on the left hand side.)' 490 ()' 491 ( Array literals MAY include the spread operator \(...\) to flatten elements)' 492 ( out of one or more other iterables. The spread operator SHOULD be used)' 493 ( instead of more awkward constructs with "Array.prototype". There is no)' 494 ( space after the "...".)' 495 ()' 496 ( 3.6. Object literals)' 497 ()' 498 ( A trailing comma SHOULD be used whenever there is a line break between the)' 499 ( final property and the closing brace.)' 500 ()' 501 ( While the Object constructor does not have the same problems as the Array)' 502 ( constructor, the Object constructor MUST NOT be used to create a new)' 503 ( object. Use an object literal instead.)' 504 ()' 505 ( When writing an object literal, unquoted keys and quoted keys MUST NOT be)' 506 ( used.)' 507 ()' 508 ( Computed property names are allowed and are considered quoted keys \(they)' 509 ( MUST NOT be mixed with non-quoted keys\) unless the computed property is a)' 510 ( symbol. Enum values may also be used for computed keys, but should not be)' 511 ( mixed with non-enum keys in the same literal.)' 512 ()' 513 ( Methods SHOULD be defined on object literals using the method shorthand in)' 514 ( place of a colon immediately followed by a function or arrow function)' 515 ( literal to be consistent with class literals.)' 516 ()' 517 ()' 518 ()' 519 ()' 520 (Bron [Page 6])' 521 ET 522 endstream 523 endobj 524 23 0 obj 525 2914 526 endobj 527 24 0 obj 528 << 529 /Type /Page 530 /Parent 3 0 R 531 /Resources 5 0 R 532 /Contents 25 0 R 533 >> 534 endobj 535 25 0 obj 536 << 537 /Length 26 0 R 538 >> 539 stream 540 BT 541 /F1 10 Tf 542 1 0 0 1 50 802 Tm 543 12 TL 544 (SPEC 0001 JavaScript Styling August 2018)' 545 ()' 546 ( 3.7. Functions)' 547 ()' 548 ( 3.7.1. Function literals)' 549 ()' 550 ( Exported top-level functions MAY be defined directly on the exports)' 551 ( object or else declared locally and exported separately. Non-exported)' 552 ( functions are encouraged and should not be declared private. Functions)' 553 ( MAY contain nested function definitions. If it is useful to give the)' 554 ( function a name, it should be assigned to a local const.)' 555 ()' 556 ( 3.7.2. Arrow function literals)' 557 ()' 558 ( Arrow function literals SHOULD be used instead of "function" literals)' 559 ( whenever applicable, unless the code is easier to read and understand)' 560 ( when not.)' 561 ()' 562 ( The right-hand side of the arrow MUST be either a single expression or)' 563 ( a block. Multiple expressions MAY NOT be concatenated into a single)' 564 ( expression using commas when used as the only statement of an arrow)' 565 ( function.)' 566 ()' 567 ( 3.7.3. Generator functions)' 568 ()' 569 ( Generators enable a number of useful abstractions and MAY be used as)' 570 ( needed. When defining generator functions, attach the "*" to the)' 571 ( "function" keyword when present and separate it with a space from the)' 572 ( name of the function. When using delegating yields, attach the "*" to)' 573 ( the "yield" keyword.)' 574 ()' 575 ( 3.7.4. Parameters)' 576 ()' 577 ( 3.7.4.1. Default parameters)' 578 ()' 579 ( Function parameters MUST be typed with JSDoc annotations in the)' 580 ( JSDoc preceding the function's definition,)' 581 ()' 582 ( Parameter types MAY be specified inline, immediately before the)' 583 ( parameter name. Inline and "@param" type annotations MUST NOT be)' 584 ( mixed in the same function definition.)' 585 ()' 586 ( Optional parameters SHOULD be indicated by using the equals operator)' 587 ( to set a default value for that parameter, even if the default value)' 588 ( should be undefined. Optional parameters indicated by a default)' 589 ( value MUST include spaces on both sides of the equals operator, be)' 590 ( named exactly like required parameters \(i.e. not prefixed\), use the)' 591 ( "=" suffix in their JSDoc type and not use initializers that produce)' 592 ( observable side effects. Optional parameters SHOULD come after)' 593 ( required parameters.)' 594 ()' 595 ( Use default parameter values sparingly. Prefer destructuring to)' 596 ( create readable APIs when there are more than a small handful of)' 597 ( optional parameters that do not have a natural order.)' 598 ()' 599 ()' 600 ()' 601 ()' 602 ()' 603 (Bron [Page 7])' 604 ET 605 endstream 606 endobj 607 26 0 obj 608 2873 609 endobj 610 27 0 obj 611 << 612 /Type /Page 613 /Parent 3 0 R 614 /Resources 5 0 R 615 /Contents 28 0 R 616 >> 617 endobj 618 28 0 obj 619 << 620 /Length 29 0 R 621 >> 622 stream 623 BT 624 /F1 10 Tf 625 1 0 0 1 50 802 Tm 626 12 TL 627 (SPEC 0001 JavaScript Styling August 2018)' 628 ()' 629 ( 3.7.4.2. Rest parameters)' 630 ()' 631 ( Use a rest parameter instead of accessing the special arguments)' 632 ( variable. Rest parameters are typed with a "..." prefix in their)' 633 ( JSDoc. The rest parameter MUST be the last parameter in the list.)' 634 ( There is no space between the "..." and the parameter name. The rest)' 635 ( parameter MUST NOT be named "arguments" or any other word which)' 636 ( confusingly shadows built-in names.)' 637 ()' 638 ( 3.7.5. Returns)' 639 ()' 640 ( Function return types MUST be specified in the JSDoc directly above the)' 641 ( function definition.)' 642 ()' 643 ( 3.7.6. Spread operator)' 644 ()' 645 ( Function calls MAY use the spread operator. The spread operator SHOULD)' 646 ( be used in preference over Function.prototype.apply when an array or)' 647 ( iterable is unpacked into multiple parameters of a variadic function.)' 648 ( There MUST NOT be a space between the spread operator and the array or)' 649 ( iterable.)' 650 ()' 651 ( 3.8. Classes)' 652 ()' 653 ( 3.8.1. Constructors)' 654 ()' 655 ( Constructors are OPTIONAL for concrete classes. Subclass constructors)' 656 ( MUST call "super\(\)" before setting any fields or otherwise accessing)' 657 ( "this", unless required to do so in order to acquite their goal.)' 658 ()' 659 ( 3.8.2. Fields)' 660 ()' 661 ( All of a concrete object's fields \(i.e. all properties other than)' 662 ( methods\) MUST be set from within the constructor. Fields that are never)' 663 ( reassigned SHOULD be annotated with "@const".)' 664 ()' 665 ( Private fields SHOULD either be annotated with "@private" or have a)' 666 ( Symbol as key. Fields MUST NOT be set on a concrete class' prototype.)' 667 ()' 668 ( 3.8.3. ES5 class declarations)' 669 ()' 670 ( While ES6 classes are preferred, there are cases where ES6 classes may)' 671 ( not be feasible.)' 672 ()' 673 ( Per-instance properties SHOULD be defined in the constructor after the)' 674 ( call to the super class constructor, if a super class exists. Methods)' 675 ( SHOULD be defined on the prototype of the constructor.)' 676 ()' 677 ()' 678 ()' 679 ()' 680 ()' 681 ()' 682 ()' 683 ()' 684 ()' 685 ()' 686 (Bron [Page 8])' 687 ET 688 endstream 689 endobj 690 29 0 obj 691 2403 692 endobj 693 30 0 obj 694 << 695 /Type /Page 696 /Parent 3 0 R 697 /Resources 5 0 R 698 /Contents 31 0 R 699 >> 700 endobj 701 31 0 obj 702 << 703 /Length 32 0 R 704 >> 705 stream 706 BT 707 /F1 10 Tf 708 1 0 0 1 50 802 Tm 709 12 TL 710 (SPEC 0001 JavaScript Styling August 2018)' 711 ()' 712 ( 3.8.4. Prototype manipulation)' 713 ()' 714 ( In ES6 class definitions, the prototype of the class SHOULD NOT be)' 715 ( manipulated directly. Ordinary implementation code has no business)' 716 ( manipulating these objects.)' 717 ()' 718 ( Mixins and modifications of the prototypes of builtin objects SHALL NOT)' 719 ( be used, unless part of framework code which otherwise would resort to)' 720 ( even-worse workarounds to avoid doing so.)' 721 ()' 722 ( 3.8.5. Getters and setters)' 723 ()' 724 ( The JavaScript getter and setter properties MUST NOT be used, unless)' 725 ( part of data-binding frameworks where they MAY be used sparingly.)' 726 ()' 727 ( 3.9. This)' 728 ()' 729 ( Only use the this builtin in class constructors and methods, or in arrow)' 730 ( functions defined within class constructors and methods. Any other uses of)' 731 ( this MUST have an explicit "@this" declared in the immediately-enclosing)' 732 ( function's JSDoc.)' 733 ()' 734 ( The this builtin SHOULD NOT be used to refer to the global object, the)' 735 ( context of an eval or the target of an event.)' 736 ()' 737 ( 3.10. Disallowed features)' 738 ()' 739 ( The "with" keyword)' 740 ( The "with" keyword MUST NOT be used. It makes your code harder to)' 741 ( understand and has been banned in strict mode since ES5.)' 742 ()' 743 ( Dynamic code evaluation)' 744 ( The "eval" method and the "Function\(...string\)" constructor MUST NOT be)' 745 ( used outside of code loaders. These features are potentially dangerous)' 746 ( and simply do not work in CSP environments.)' 747 ()' 748 ( Automatic semicolon insertion)' 749 ( Always terminate statements with semicolons, except for function and)' 750 ( class declarations.)' 751 ()' 752 ( Non-standard features)' 753 ( Non-standard features MUST NOT be used. This includes old features that)' 754 ( have been removed, new features that are not yet standardized or)' 755 ( proprietary that are only implemented in some JavaScript environments.)' 756 ( These features are only allowed if the code being written is intended)' 757 ( for only that environment.)' 758 ()' 759 ( Wrapper objects for primitive types)' 760 ( Never use the "new" keyword on primitive object wrappers nor include)' 761 ( them in type annotations. The wrappers MAY be called as functions for)' 762 ( coercing \(which is preferred over using "+" or concatenating the empty)' 763 ( string\) or creating Symbols.)' 764 ()' 765 ()' 766 ()' 767 ()' 768 ()' 769 (Bron [Page 9])' 770 ET 771 endstream 772 endobj 773 32 0 obj 774 2710 775 endobj 776 33 0 obj 777 << 778 /Type /Page 779 /Parent 3 0 R 780 /Resources 5 0 R 781 /Contents 34 0 R 782 >> 783 endobj 784 34 0 obj 785 << 786 /Length 35 0 R 787 >> 788 stream 789 BT 790 /F1 10 Tf 791 1 0 0 1 50 802 Tm 792 12 TL 793 (SPEC 0001 JavaScript Styling August 2018)' 794 ()' 795 (4. Naming)' 796 ()' 797 ( 4.1. Rules for all identifiers)' 798 ()' 799 ( Identifiers MUST use only ASCII letters, digits, underscores and the)' 800 ( dollar sign.)' 801 ()' 802 ( Give as descriptive a name as possible, within reason. Do not worry about)' 803 ( saving horizontal space as it is far more important to make your code)' 804 ( immediately understandable by a new reader. Do not use abbreviations that)' 805 ( are ambiguous or unfamiliar to readers outside your project and do not)' 806 ( abbreviate by deleting letters within a word.)' 807 ()' 808 ( 4.2. Rules by identifier type)' 809 ()' 810 ( Package names ................................................. kebab-case)' 811 ( Class names ............................................... UpperCamelCase)' 812 ( Method names .............................................. lowerCamelCase)' 813 ( Enum names ................................................ UpperCamelCase)' 814 ( Constant names ...................................... SCREAMING_SNAKE_CASE)' 815 ( Non-constant field names .................................. lowerCamelCase)' 816 ( Parameter names ........................................... lowerCamelCase)' 817 ( Local variable names ...................................... lowerCamelCase)' 818 ( Template parameter names ............................ SCREAMING_SNAKE_CASE)' 819 ()' 820 (5. JSDoc)' 821 ()' 822 ( 5.1. General form)' 823 ()' 824 ( JSDoc is a generic docblock \(/**\) with a body as defined here. JSDoc is)' 825 ( either multi-line or single-line, where the single-line version MUST)' 826 ( follow the parameter or field section of the multi-line version.)' 827 ()' 828 ( There are many tools which extract metadata from JSDoc comments to perform)' 829 ( code validation and optimization. As such, these comments MUST be)' 830 ( well-formed.)' 831 ()' 832 ( A JSDoc comment can contain the following sections, which are described in)' 833 ( 5.2. through 5.4.:)' 834 ( - Summary)' 835 ( - Description)' 836 ( - Tags)' 837 ()' 838 ( 5.2. Summary)' 839 ()' 840 ( The summary is a one-line string used to give an impression of the)' 841 ( function of the documented element. This can be used in overviews to allow)' 842 ( the user to skim the documentation in search of the required template.)' 843 ()' 844 ()' 845 ()' 846 ()' 847 ()' 848 ()' 849 ()' 850 ()' 851 ()' 852 (Bron [Page 10])' 853 ET 854 endstream 855 endobj 856 35 0 obj 857 2505 858 endobj 859 36 0 obj 860 << 861 /Type /Page 862 /Parent 3 0 R 863 /Resources 5 0 R 864 /Contents 37 0 R 865 >> 866 endobj 867 37 0 obj 868 << 869 /Length 38 0 R 870 >> 871 stream 872 BT 873 /F1 10 Tf 874 1 0 0 1 50 802 Tm 875 12 TL 876 (SPEC 0001 JavaScript Styling August 2018)' 877 ()' 878 ( 5.3. Description)' 879 ()' 880 ( The description contains concise information about the function of the)' 881 ( documented element. The description MUST be in Markdown markup to apply)' 882 ( styling.)' 883 ()' 884 ( The following list has examples of types of information that can be)' 885 ( contained in a description:)' 886 ( - Explanation of algorithms)' 887 ( - Code examples)' 888 ( - Array specification)' 889 ( - Relation to other elements)' 890 ( - License information \(in the case of file documentation\))' 891 ()' 892 ( Descriptions can also contain inline tags. These are special annotations)' 893 ( that can be substituted for a specialized type of information \(such as)' 894 ( {@link}\). Inline tags MUST always be surrounded by braces.)' 895 ()' 896 ()' 897 ()' 898 ()' 899 ()' 900 ()' 901 ()' 902 ()' 903 ()' 904 ()' 905 ()' 906 ()' 907 ()' 908 ()' 909 ()' 910 ()' 911 ()' 912 ()' 913 ()' 914 ()' 915 ()' 916 ()' 917 ()' 918 ()' 919 ()' 920 ()' 921 ()' 922 ()' 923 ()' 924 ()' 925 ()' 926 ()' 927 ()' 928 ()' 929 ()' 930 ()' 931 ()' 932 ()' 933 ()' 934 ()' 935 (Bron [Page 11])' 936 ET 937 endstream 938 endobj 939 38 0 obj 940 1142 941 endobj 942 39 0 obj 943 << 944 /Type /Page 945 /Parent 3 0 R 946 /Resources 5 0 R 947 /Contents 40 0 R 948 >> 949 endobj 950 40 0 obj 951 << 952 /Length 41 0 R 953 >> 954 stream 955 BT 956 /F1 10 Tf 957 1 0 0 1 50 802 Tm 958 12 TL 959 (SPEC 0001 JavaScript Styling August 2018)' 960 ()' 961 ( 5.4. Tags)' 962 ()' 963 ( Tags represent metadata with which IDEs, external tooling or even the)' 964 ( application itself know how to interpret an element.)' 965 ()' 966 ( 5.4.1. JSDoc tag reference)' 967 ()' 968 ( The following tags are common and well supported by various)' 969 ( documentation generation tools \(such as JsDossier\) for purely)' 970 ( documentation purposes.)' 971 ()' 972 ( Tag Description)' 973 ()' 974 ( @author Document the author of a file or the owner of a)' 975 ( @owner test, generally only used in the @fileoverview comment.)' 976 ( Not recommended.)' 977 ()' 978 ( @bug Indicates what bugs the given test function regression)' 979 ( tests. Multiple bugs should each have their own @bug)' 980 ( line, to make searching for regression tests as easy as)' 981 ( possible.)' 982 ()' 983 ( @see Reference a lookup to another class function or method,)' 984 ( global function, file or URL.)' 985 ()' 986 ( @param Indicates the type of a function or method parameter,)' 987 ( optionally adding a description to further explain what)' 988 ( the described parameter does.)' 989 ()' 990 ( @return Indicates the return type of a function or method,)' 991 ( optionally adding a description to further explain what)' 992 ( the return value contains.)' 993 ()' 994 ( @type Indicate the documented element's type.)' 995 ()' 996 ( @const Describes the documented element is a constant variable,)' 997 ( that it MUST NOT be reassigned later.)' 998 ()' 999 ( @private Describes the documented element is private and care MUST)' 1000 ( be taken to not expose the element to scopes other than)' 1001 ( the one it is declared in.)' 1002 ()' 1003 ( @this Indicates the documented element uses the "this" keyword)' 1004 ( and SHOULD be handled with care in relation to it's)' 1005 ( context.)' 1006 ()' 1007 ( @override Indicates the documented method overrides the)' 1008 ( equally-named super class method.)' 1009 ()' 1010 ( @deprecated Indicates the documented element is deprecated and this)' 1011 ( SHOULD not be used in new code.)' 1012 ()' 1013 ()' 1014 ()' 1015 ()' 1016 ()' 1017 ()' 1018 (Bron [Page 12])' 1019 ET 1020 endstream 1021 endobj 1022 41 0 obj 1023 2627 1024 endobj 1025 42 0 obj 1026 << 1027 /Type /Page 1028 /Parent 3 0 R 1029 /Resources 5 0 R 1030 /Contents 43 0 R 1031 >> 1032 endobj 1033 43 0 obj 1034 << 1035 /Length 44 0 R 1036 >> 1037 stream 1038 BT 1039 /F1 10 Tf 1040 1 0 0 1 50 802 Tm 1041 12 TL 1042 (SPEC 0001 JavaScript Styling August 2018)' 1043 ()' 1044 ( 5.5. Line wrapping)' 1045 ()' 1046 ( Line-wrapped block texts MUST be indented four spaces or be aligned with)' 1047 ( the start of the text when it's a comment on a tag.)' 1048 ()' 1049 ( Wrapped description text SHOULD be lined up with the description on)' 1050 ( previous lines.)' 1051 ()' 1052 ( 5.6. Top/file-level comments)' 1053 ()' 1054 ( A file MAY have a top-level overview. A copyright notice and author)' 1055 ( information are optional. File overviews are recommended whenever a file)' 1056 ( consists of more than a single class definition. The top level comment is)' 1057 ( designed to orient readers unfamiliar with the code to what is in this)' 1058 ( file. If present, it MAY provide a description of the file's contents and)' 1059 ( any dependencies or compatibility information. Line wrapping MUST follow)' 1060 ( the rules defined in section 5.5.)' 1061 ()' 1062 ( 5.7. Class comments)' 1063 ()' 1064 ( Classes, interfaces and records MUST be documented with a description and)' 1065 ( any template parameters, implemented interfaces and other appropriate)' 1066 ( tags. The class description SHOULD provide the reader with enough)' 1067 ( information to know how and when to use the class, as wel as any)' 1068 ( additional considerations necessary to correctly use the class. Textual)' 1069 ( descriptions MAY be omitted on the constructor.)' 1070 ()' 1071 ( 5.8. Enum and typedef comments)' 1072 ()' 1073 ( Enums and typedefs MUST be documented. Public enums and typedefs MUST have)' 1074 ( a non-empty description. Individual enum items may be documented with a)' 1075 ( JSDoc comment on the preceding line.)' 1076 ()' 1077 ( 5.9. Method and function comments)' 1078 ()' 1079 ( Parameter and return types MUST be documented. The "this" type should be)' 1080 ( documented when necessary. Method, parameter and return descriptions \(but)' 1081 ( not types\) MAY be omitted if they are obvious from the rest of the)' 1082 ( method's JSDoc or from it's signature. Method descriptions SHOULD start)' 1083 ( with a sentence written in the third person declarative voice \(a.k.a. the)' 1084 ( summary\).)' 1085 ()' 1086 ( If a method overrides a superclass method, it must include an @override)' 1087 ( annotation. Overridden methods must include all @param and @return)' 1088 ( annotations if any types are refined, but SHOULD emit them if the types)' 1089 ( are all the same.)' 1090 ()' 1091 ( Anonymous functions do not require JSDoc, though parameters may be)' 1092 ( specified inline if the automatic type inference is insufficient.)' 1093 ()' 1094 ()' 1095 ()' 1096 ()' 1097 ()' 1098 ()' 1099 ()' 1100 ()' 1101 (Bron [Page 13])' 1102 ET 1103 endstream 1104 endobj 1105 44 0 obj 1106 2734 1107 endobj 1108 45 0 obj 1109 << 1110 /Type /Page 1111 /Parent 3 0 R 1112 /Resources 5 0 R 1113 /Contents 46 0 R 1114 >> 1115 endobj 1116 46 0 obj 1117 << 1118 /Length 47 0 R 1119 >> 1120 stream 1121 BT 1122 /F1 10 Tf 1123 1 0 0 1 50 802 Tm 1124 12 TL 1125 (SPEC 0001 JavaScript Styling August 2018)' 1126 ()' 1127 ( 5.10. Property comments)' 1128 ()' 1129 ( Property types must be documented. The description may be omitted for)' 1130 ( private properties, if name and type provide enough documentation for)' 1131 ( understanding the code.)' 1132 ()' 1133 ( Publicly exported constants are commented the same way as properties.)' 1134 ( Explicit types may be omitted for @const properties initialized from an)' 1135 ( expression with an obviously known type.)' 1136 ()' 1137 ( 5.11. Nullability)' 1138 ()' 1139 ( When defining the type of a parameter or other element, nullability SHOULD)' 1140 ( be indicated by either "!" or "?" as a prefix of the type for non-null and)' 1141 ( nullable, respectively. Primitive types are nullable by default but cannot)' 1142 ( be immediately distinguished from a name that is typed to a)' 1143 ( non-null-by-default type. As such, all types except primitives and record)' 1144 ( literals SHOULD be annotated explicitly with either "?" or "!" to indicate)' 1145 ( whether they are nullable or not.)' 1146 ()' 1147 ( 5.12. Template parameter types)' 1148 ()' 1149 ( Whenever possible, one SHOULD specify template parameters when dealing)' 1150 ( with elements which by default contain other elements, such as Objects,)' 1151 ( Arrays or a Promise.)' 1152 ()' 1153 ( Objects MUST NOT specify template parameters when used as a hierarchy)' 1154 ( instead of a map-like structure.)' 1155 ()' 1156 (6. Policies)' 1157 ()' 1158 ( 6.1. Unspecified styling)' 1159 ()' 1160 ( For any style question that isn't settled definitively by this)' 1161 ( specification, one SHOULD follow the code style of the rest of the file.)' 1162 ( If that doesn't resolve the question, consider emulating the other files)' 1163 ( in the same package. If that still does not resolve the question, follow)' 1164 ( the rules set by standardjs.)' 1165 ()' 1166 ( As a rule of thumb: be consistent throughout the package.)' 1167 ()' 1168 ( 6.2. Deprecation)' 1169 ()' 1170 ( Mark deprecated methods, classes, interfaces or functions with @deprecated)' 1171 ( annotations. A deprecation comment MUST include simple, clear directions)' 1172 ( for people to fix their call sites.)' 1173 ()' 1174 ( 6.3. Code not in Finwo Style)' 1175 ()' 1176 ( You will occasionally encounter files in your codebase that are not in)' 1177 ( proper Finwo Style. These may have come from an acquisition, or may have)' 1178 ( been written before Finwo Style took a position on some issue, or may be)' 1179 ( in non-Finwo Style for any other reason.)' 1180 ()' 1181 ()' 1182 ()' 1183 ()' 1184 (Bron [Page 14])' 1185 ET 1186 endstream 1187 endobj 1188 47 0 obj 1189 2655 1190 endobj 1191 48 0 obj 1192 << 1193 /Type /Page 1194 /Parent 3 0 R 1195 /Resources 5 0 R 1196 /Contents 49 0 R 1197 >> 1198 endobj 1199 49 0 obj 1200 << 1201 /Length 50 0 R 1202 >> 1203 stream 1204 BT 1205 /F1 10 Tf 1206 1 0 0 1 50 802 Tm 1207 12 TL 1208 (SPEC 0001 JavaScript Styling August 2018)' 1209 ()' 1210 ( 6.3.1. Reformatting existing code)' 1211 ()' 1212 ( When working on the file, only reformat the functions and/or methods)' 1213 ( you change instead of the whole file. If significant changes are being)' 1214 ( made to a file, it is expected that the file will be in Finwo Style.)' 1215 ()' 1216 ( 6.3.2. Newly added code)' 1217 ()' 1218 ( Brand new files MUST use Finwo style, regardless of style choices of)' 1219 ( other files in the same package. When adding new code to a file that is)' 1220 ( not in Finwo Style, reformatting the existing code first is)' 1221 ( recommended, subject to the advice in section 6.3.1.)' 1222 ()' 1223 ( If this reformatting is not done, the new code should be as consistent)' 1224 ( as possible with existing code in the same file, but MUST not break any)' 1225 ( rules of this specification.)' 1226 ()' 1227 ( 6.4. Local style rules)' 1228 ()' 1229 ( Teams and projects may adopt additional style rules beyond those in this)' 1230 ( document, but must accept that cleanup changes may not abide by these)' 1231 ( additional rules, and must not block such cleanup changes due to violating)' 1232 ( any additional rules. Beware of excessive rules which serve no purpose.)' 1233 ( The style guide does not seek to define style in every possible scenario)' 1234 ( and neither should you.)' 1235 ()' 1236 ( 6.5. Generated code)' 1237 ()' 1238 ( Source code generate by any build process is not required to be in Finwo)' 1239 ( Style. However, any generated identifiers that will by referenced from)' 1240 ( hand-written code must follow the naming requirements. As a special)' 1241 ( exception, such identifiers are allowed to contain underscores, which may)' 1242 ( help to avoid conflicts with hand-written identifiers.)' 1243 ()' 1244 ( 6.6. Third-party code)' 1245 ()' 1246 ( This style specification does not apply to third-party code used within)' 1247 ( the package. When working on third-party code embedded in the package,)' 1248 ( section 6.3 applies.)' 1249 ()' 1250 ( When working on third-party code which is not embedded in the package, you)' 1251 ( MUST follow the style guide supplied by that project if available.)' 1252 ()' 1253 ()' 1254 ()' 1255 ()' 1256 ()' 1257 ()' 1258 ()' 1259 ()' 1260 ()' 1261 ()' 1262 ()' 1263 ()' 1264 ()' 1265 ()' 1266 ()' 1267 (Bron [Page 15])' 1268 ET 1269 endstream 1270 endobj 1271 50 0 obj 1272 2408 1273 endobj 1274 51 0 obj 1275 << 1276 /Type /Page 1277 /Parent 3 0 R 1278 /Resources 5 0 R 1279 /Contents 52 0 R 1280 >> 1281 endobj 1282 52 0 obj 1283 << 1284 /Length 53 0 R 1285 >> 1286 stream 1287 BT 1288 /F1 10 Tf 1289 1 0 0 1 50 802 Tm 1290 12 TL 1291 (SPEC 0001 JavaScript Styling August 2018)' 1292 ()' 1293 (7. Informative resources)' 1294 ()' 1295 ( [JSGUIDE] Google JavaScript Style Guide)' 1296 ( https://google.github.io/styleguide/jsguide)' 1297 ()' 1298 ( [STANDARDJS] StandardJS standard style)' 1299 ( https://standardjs.com/rules)' 1300 ()' 1301 ( [kebab-case] Special case styles)' 1302 ( https://en.wikipedia.org/wiki/Kebab_case)' 1303 ()' 1304 ( [camel-case] Camel case)' 1305 ( https://en.wikipedia.org/wiki/Camel_case)' 1306 ()' 1307 ( [SCREAMING_SNAKE_CASE] Snake case)' 1308 ( https://en.wikipedia.org/wiki/Snake_case)' 1309 ()' 1310 ( [RFC20] ASCII format for Network Interchange)' 1311 ( Vint Cerf)' 1312 ( https://tools.ietf.org/html/rfc20)' 1313 ()' 1314 ( [RFC2119] RFC Key Words)' 1315 ( S. Bradner)' 1316 ( https://tools.ietf.org/html/rfc2119)' 1317 ()' 1318 ( [RFC3629] UTF-8)' 1319 ( F. Yergeau)' 1320 ( https://tools.ietf.org/html/rfc3629)' 1321 ()' 1322 ()' 1323 ()' 1324 ()' 1325 ()' 1326 ()' 1327 ()' 1328 ()' 1329 ()' 1330 ()' 1331 ()' 1332 ()' 1333 ()' 1334 ()' 1335 ()' 1336 ()' 1337 ()' 1338 ()' 1339 ()' 1340 ()' 1341 ()' 1342 ()' 1343 ()' 1344 ()' 1345 ()' 1346 ()' 1347 ()' 1348 ()' 1349 ()' 1350 (Bron [Page 16])' 1351 ET 1352 endstream 1353 endobj 1354 53 0 obj 1355 1428 1356 endobj 1357 54 0 obj 1358 << 1359 /Type /Page 1360 /Parent 3 0 R 1361 /Resources 5 0 R 1362 /Contents 55 0 R 1363 >> 1364 endobj 1365 55 0 obj 1366 << 1367 /Length 56 0 R 1368 >> 1369 stream 1370 BT 1371 /F1 10 Tf 1372 1 0 0 1 50 802 Tm 1373 12 TL 1374 (SPEC 0001 JavaScript Styling August 2018)' 1375 ()' 1376 (8. Author information)' 1377 ()' 1378 ( Name ....... Robin Bron)' 1379 ( Nickname ... Finwo)' 1380 ( EMail ...... robin@finwo.nl)' 1381 ()' 1382 ()' 1383 ()' 1384 ()' 1385 ()' 1386 ()' 1387 ()' 1388 ()' 1389 ()' 1390 ()' 1391 ()' 1392 ()' 1393 ()' 1394 ()' 1395 ()' 1396 ()' 1397 ()' 1398 ()' 1399 ()' 1400 ()' 1401 ()' 1402 ()' 1403 ()' 1404 ()' 1405 ()' 1406 ()' 1407 ()' 1408 ()' 1409 ()' 1410 ()' 1411 ()' 1412 ()' 1413 ()' 1414 ()' 1415 ()' 1416 ()' 1417 ()' 1418 ()' 1419 ()' 1420 ()' 1421 ()' 1422 ()' 1423 ()' 1424 ()' 1425 ()' 1426 ()' 1427 ()' 1428 ()' 1429 ()' 1430 ()' 1431 ()' 1432 ()' 1433 (Bron [Page 17])' 1434 ET 1435 endstream 1436 endobj 1437 56 0 obj 1438 538 1439 endobj 1440 3 0 obj 1441 << 1442 /Type /Pages 1443 /Count 17 1444 /MediaBox [ 0 0 595 842 ] 1445 /Kids [ 6 0 R 9 0 R 12 0 R 15 0 R 18 0 R 21 0 R 24 0 R 27 0 R 30 0 R 33 0 R 36 0 R 39 0 R 42 0 R 45 0 R 48 0 R 51 0 R 54 0 R ] 1446 >> 1447 endobj 1448 xref 1449 0 57 1450 0000000000 65535 f 0000000009 00000 n 0000000148 00000 n 0000042100 00000 n 0000000197 00000 n 0000000275 00000 n 0000000346 00000 n 0000000426 00000 n 0000001623 00000 n 0000001643 00000 n 0000001724 00000 n 0000006475 00000 n 0000006496 00000 n 0000006578 00000 n 0000007952 00000 n 0000007973 00000 n 0000008055 00000 n 0000010545 00000 n 0000010566 00000 n 0000010648 00000 n 0000013259 00000 n 0000013280 00000 n 0000013362 00000 n 0000016330 00000 n 0000016351 00000 n 0000016433 00000 n 0000019360 00000 n 0000019381 00000 n 0000019463 00000 n 0000021920 00000 n 0000021941 00000 n 0000022023 00000 n 0000024787 00000 n 0000024808 00000 n 0000024890 00000 n 0000027449 00000 n 0000027470 00000 n 0000027552 00000 n 0000028748 00000 n 0000028769 00000 n 0000028851 00000 n 0000031532 00000 n 0000031553 00000 n 0000031635 00000 n 0000034423 00000 n 0000034444 00000 n 0000034526 00000 n 0000037235 00000 n 0000037256 00000 n 0000037338 00000 n 0000039800 00000 n 0000039821 00000 n 0000039903 00000 n 0000041385 00000 n 0000041406 00000 n 0000041488 00000 n 0000042080 00000 n trailer 1451 << 1452 /Size 57 1453 /Root 2 0 R 1454 /Info 1 0 R 1455 >> 1456 startxref 1457 42297 1458 %%EOF