document.txt (35296B)
1 Specification: 0001 Robin Bron 2 August 2018 3 4 5 6 JavaScript Styling 7 8 9 This document describes a set of rules for JavaScript source code. To apply 10 these rules, include the next paragraph near the beginning of the documentation 11 of the project or near the beginning of the generic README file of the project: 12 13 The JavaScript source code in this project must adhere to the rules as 14 described in FINWO/SPEC0001 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Copyright Notice 53 54 This document is licensed under a 55 Creative Commons Attribution 4.0 International License 56 57 You should have received a copy of the license along with this work. If not, 58 see <http://creativecommons.org/licenses/by/4.0/> 59 60 Bron [Page 1] 61 SPEC 0001 JavaScript Styling August 2018 62 63 Table of contents 64 65 1. Introduction ........................................................... 4 66 1.1. Conventions ....................................................... 4 67 2. Source file basics ..................................................... 4 68 2.1. File name ......................................................... 4 69 2.2. File encoding ..................................................... 4 70 2.3. Special characters ................................................ 4 71 2.3.1. Whitespace characters ........................................ 4 72 2.3.2. Special escape sequences ..................................... 4 73 2.3.3. Non-ASCII characters ......................................... 4 74 3. Formatting ............................................................. 5 75 3.1. Braces ............................................................ 5 76 3.1.1. Control structures ........................................... 5 77 3.1.2. Non-empty blocks ............................................. 5 78 3.1.3. Empty blocks ................................................. 5 79 3.2. Indentation ....................................................... 5 80 3.3. String literals ................................................... 5 81 3.4. Number literals ................................................... 6 82 3.5. Array literals .................................................... 6 83 3.6. Object literals ................................................... 6 84 3.7. Functions ......................................................... 7 85 3.7.1. Function literals ............................................ 7 86 3.7.2. Arrow function literals ...................................... 7 87 3.7.3. Generator functions .......................................... 7 88 3.7.4. Parameters ................................................... 7 89 3.7.4.1. Default parameters ...................................... 7 90 3.7.4.2. Rest parameters ......................................... 8 91 3.7.5. Returns ...................................................... 8 92 3.7.6. Spread operator .............................................. 8 93 3.8. Classes ........................................................... 8 94 3.8.1. Constructors ................................................. 8 95 3.8.2. Fields ....................................................... 8 96 3.8.3. ES5 class declarations ....................................... 8 97 3.8.4. Prototype manipulation ....................................... 9 98 3.8.5. Getters and setters .......................................... 9 99 3.9. This .............................................................. 9 100 3.10. Disallowed features .............................................. 9 101 4. Naming ................................................................ 10 102 4.1. Rules for all identifiers ........................................ 10 103 4.2. Rules by identifier type ......................................... 10 104 5. JSDoc ................................................................. 10 105 5.1. General form .................................................... 10 106 5.2. Summary ......................................................... 10 107 5.3. Description ..................................................... 11 108 5.4. Tags ............................................................ 12 109 5.4.1. JSDoc tag reference ......................................... 12 110 5.5. Line wrapping ................................................... 13 111 5.6. Top/file-level comments ......................................... 13 112 5.7. Class comments .................................................. 13 113 5.8. Enum and typedef comments ....................................... 13 114 5.9. Method and function comments .................................... 13 115 5.10. Property comments ............................................... 14 116 5.11. Nullability ..................................................... 14 117 5.12. Template parameter types ........................................ 14 118 119 120 Bron [Page 2] 121 SPEC 0001 JavaScript Styling August 2018 122 123 6. Policies .............................................................. 14 124 6.1. Unspecified styling .............................................. 14 125 6.2. Deprecation ...................................................... 14 126 6.3. Code not in Finwo Style .......................................... 14 127 6.3.1. Reformatting existing code .................................. 15 128 6.3.2. Newly added code ............................................ 15 129 6.4. Local style rules ................................................ 15 130 6.5. Generated code ................................................... 15 131 6.6. Third-party code ................................................. 15 132 7. Informative resources ................................................. 16 133 8. Author information .................................................... 17 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 Bron [Page 3] 181 SPEC 0001 JavaScript Styling August 2018 182 183 1. Introduction 184 185 This document serves as the complete definition of the coding standards for 186 source code in the JavaScript programming language as followed by finwo. A 187 JavaScript source file is described as being in "Finwo Style" if, and only 188 if, it adheres to the rules herein. 189 190 Like other programming style guides, the issues covered span not only 191 aesthetic issues of formatting, but other types of conventions or coding 192 standards as well. However, this document focuses primarily on the 193 hard-and-fast rules that we follow universally, and avoids giving advice that 194 isn't clearly enforceable (whether by human or tool). 195 196 1.1. Conventions 197 198 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 199 "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 200 document are to be interpreted as described in RFC2119 when, and only when, 201 they appear in all capitals, as shown here. 202 203 2. Source file basics 204 205 2.1. File name 206 207 File names MUST be all lowercase and may include underscores (_) or dashes 208 (-), but no additional punctuation. The extension MUST always be ".js". 209 210 2.2. File encoding 211 212 Source files MUST always be encoded according to the UTF-8 standard (See 213 RFC3629). 214 215 2.3. Special characters 216 217 2.3.1 Whitespace characters 218 219 Aside from the line-feed character, the ASCII (See RFC20) horizonal 220 space character (0x20) is the only whitespace character that appears 221 anywhere in a source files. 222 223 2.3.2. Special escape sequences 224 225 For any character that has a special escape sequence, that sequence 226 SHOULD be used rather than the corresponding numeric escape sequence. 227 Legacy octal escapes MUST NOT be used. 228 229 2.3.3. Non-ASCII characters 230 231 For the remaining non-ASCII characters, either the actual Unicode 232 character or the equivalent hex or Unicode escape is used, depending 233 only on which makes the code easier to read and understand. 234 235 236 237 238 239 240 Bron [Page 4] 241 SPEC 0001 JavaScript Styling August 2018 242 243 3. Formatting 244 245 3.1. Braces 246 247 3.1.1. Control structures 248 249 Braces are REQUIRED for all control structures (i.e. if, else, for, do, 250 while, as wel as any others). The first statement of a non-empty block 251 MUST begin on its own line. 252 253 Control structures SHOULD omit braces and be written on a single line 254 if the both the statement and the control structure can be kept on a 255 single line without wrapping when it improves readability. 256 257 3.1.2. Non-empty blocks 258 259 Braces follow the Kernighan and Ritchie style ("Egyptian brackets") for 260 non-empty blocks and block-like structures. 261 262 - No line break before the opening brace 263 - Line break after the opening brace 264 - Line break before the closing brace 265 - Line break after the closing brace if that brace terminates a 266 statement or the body of a function or class statement, or a class 267 method. Specifically, there is no line break after the brace if it is 268 followed by "else", "catch", "while", or a comma, semicolon, or 269 right-prarenthesis. 270 271 3.1.3. Empty blocks 272 273 An empty block or block-like construct SHOULD be closed immediately 274 after it is opened, with no characters, space, or line break in 275 between, unless it is part of a multi-block statement. 276 277 3.2. Indentation 278 279 Each time a new block or block-like construct is opened, the indent 280 increases by two spaces. When the block ends, the indent returns to the 281 previous indent level. The indent level applies to both code and comments 282 throughout the block. 283 284 3.3. String literals 285 286 Ordinary string literals SHOULD be delimited with single quotes (') and 287 MUST NOT span multiple lines. 288 289 To prevent complex string concatenation, template strings (delimited with 290 `) SHOULD be used. Template strings (delimted with backticks (`)) MAY span 291 multiple lines in which case they SHOULD adhere the indent level of the 292 enclosing block if the whitespace does not affect functionality or 293 increases the comlexity of the code. 294 295 296 297 298 299 300 Bron [Page 5] 301 SPEC 0001 JavaScript Styling August 2018 302 303 3.4. Number literals 304 305 Numbers may be specified in decimal, hexidecimal, octal or binary. Use 306 exactly "0x", "0o" and "0b" prefixes, with lowercase characters, for hex, 307 octal and binary respectively. Never include a leading zero unless it is 308 immediately followed by "x", "o" or "b". 309 310 3.5. Array literals 311 312 Array literals SHOULD include a trailing comma whenever there is a line 313 break between the final element and the closing bracket. 314 315 The variadic Array constructor MUST NOT be used for creating a new array, 316 unless used for allocating an empty array of a given length. 317 318 Non-numeric properties on an array other than "length" or a Symbol MUST 319 NOT be used. Use a Map or Object instead. 320 321 Array literals MAY be used on the left-hand side of an assignment to 322 perform destructuring (such as when unpacking multiple values from a 323 single array or iterable). A final "rest" element MAY be included (with no 324 space between the "..." and the variable name). 325 326 Destructuring MAY also be used for function parameters (note that a 327 parameter name is required but ignored). Always specify "[]" as the 328 default value if a destructured array parameter is optional, and provide 329 default values on the left hand side. 330 331 Array literals MAY include the spread operator (...) to flatten elements 332 out of one or more other iterables. The spread operator SHOULD be used 333 instead of more awkward constructs with "Array.prototype". There is no 334 space after the "...". 335 336 3.6. Object literals 337 338 A trailing comma SHOULD be used whenever there is a line break between the 339 final property and the closing brace. 340 341 While the Object constructor does not have the same problems as the Array 342 constructor, the Object constructor MUST NOT be used to create a new 343 object. Use an object literal instead. 344 345 When writing an object literal, unquoted keys and quoted keys MUST NOT be 346 used. 347 348 Computed property names are allowed and are considered quoted keys (they 349 MUST NOT be mixed with non-quoted keys) unless the computed property is a 350 symbol. Enum values may also be used for computed keys, but should not be 351 mixed with non-enum keys in the same literal. 352 353 Methods SHOULD be defined on object literals using the method shorthand in 354 place of a colon immediately followed by a function or arrow function 355 literal to be consistent with class literals. 356 357 358 359 360 Bron [Page 6] 361 SPEC 0001 JavaScript Styling August 2018 362 363 3.7. Functions 364 365 3.7.1. Function literals 366 367 Exported top-level functions MAY be defined directly on the exports 368 object or else declared locally and exported separately. Non-exported 369 functions are encouraged and should not be declared private. Functions 370 MAY contain nested function definitions. If it is useful to give the 371 function a name, it should be assigned to a local const. 372 373 3.7.2. Arrow function literals 374 375 Arrow function literals SHOULD be used instead of "function" literals 376 whenever applicable, unless the code is easier to read and understand 377 when not. 378 379 The right-hand side of the arrow MUST be either a single expression or 380 a block. Multiple expressions MAY NOT be concatenated into a single 381 expression using commas when used as the only statement of an arrow 382 function. 383 384 3.7.3. Generator functions 385 386 Generators enable a number of useful abstractions and MAY be used as 387 needed. When defining generator functions, attach the "*" to the 388 "function" keyword when present and separate it with a space from the 389 name of the function. When using delegating yields, attach the "*" to 390 the "yield" keyword. 391 392 3.7.4. Parameters 393 394 3.7.4.1. Default parameters 395 396 Function parameters MUST be typed with JSDoc annotations in the 397 JSDoc preceding the function's definition, 398 399 Parameter types MAY be specified inline, immediately before the 400 parameter name. Inline and "@param" type annotations MUST NOT be 401 mixed in the same function definition. 402 403 Optional parameters SHOULD be indicated by using the equals operator 404 to set a default value for that parameter, even if the default value 405 should be undefined. Optional parameters indicated by a default 406 value MUST include spaces on both sides of the equals operator, be 407 named exactly like required parameters (i.e. not prefixed), use the 408 "=" suffix in their JSDoc type and not use initializers that produce 409 observable side effects. Optional parameters SHOULD come after 410 required parameters. 411 412 Use default parameter values sparingly. Prefer destructuring to 413 create readable APIs when there are more than a small handful of 414 optional parameters that do not have a natural order. 415 416 417 418 419 420 Bron [Page 7] 421 SPEC 0001 JavaScript Styling August 2018 422 423 3.7.4.2. Rest parameters 424 425 Use a rest parameter instead of accessing the special arguments 426 variable. Rest parameters are typed with a "..." prefix in their 427 JSDoc. The rest parameter MUST be the last parameter in the list. 428 There is no space between the "..." and the parameter name. The rest 429 parameter MUST NOT be named "arguments" or any other word which 430 confusingly shadows built-in names. 431 432 3.7.5. Returns 433 434 Function return types MUST be specified in the JSDoc directly above the 435 function definition. 436 437 3.7.6. Spread operator 438 439 Function calls MAY use the spread operator. The spread operator SHOULD 440 be used in preference over Function.prototype.apply when an array or 441 iterable is unpacked into multiple parameters of a variadic function. 442 There MUST NOT be a space between the spread operator and the array or 443 iterable. 444 445 3.8. Classes 446 447 3.8.1. Constructors 448 449 Constructors are OPTIONAL for concrete classes. Subclass constructors 450 MUST call "super()" before setting any fields or otherwise accessing 451 "this", unless required to do so in order to acquite their goal. 452 453 3.8.2. Fields 454 455 All of a concrete object's fields (i.e. all properties other than 456 methods) MUST be set from within the constructor. Fields that are never 457 reassigned SHOULD be annotated with "@const". 458 459 Private fields SHOULD either be annotated with "@private" or have a 460 Symbol as key. Fields MUST NOT be set on a concrete class' prototype. 461 462 3.8.3. ES5 class declarations 463 464 While ES6 classes are preferred, there are cases where ES6 classes may 465 not be feasible. 466 467 Per-instance properties SHOULD be defined in the constructor after the 468 call to the super class constructor, if a super class exists. Methods 469 SHOULD be defined on the prototype of the constructor. 470 471 472 473 474 475 476 477 478 479 480 Bron [Page 8] 481 SPEC 0001 JavaScript Styling August 2018 482 483 3.8.4. Prototype manipulation 484 485 In ES6 class definitions, the prototype of the class SHOULD NOT be 486 manipulated directly. Ordinary implementation code has no business 487 manipulating these objects. 488 489 Mixins and modifications of the prototypes of builtin objects SHALL NOT 490 be used, unless part of framework code which otherwise would resort to 491 even-worse workarounds to avoid doing so. 492 493 3.8.5. Getters and setters 494 495 The JavaScript getter and setter properties MUST NOT be used, unless 496 part of data-binding frameworks where they MAY be used sparingly. 497 498 3.9. This 499 500 Only use the this builtin in class constructors and methods, or in arrow 501 functions defined within class constructors and methods. Any other uses of 502 this MUST have an explicit "@this" declared in the immediately-enclosing 503 function's JSDoc. 504 505 The this builtin SHOULD NOT be used to refer to the global object, the 506 context of an eval or the target of an event. 507 508 3.10. Disallowed features 509 510 The "with" keyword 511 The "with" keyword MUST NOT be used. It makes your code harder to 512 understand and has been banned in strict mode since ES5. 513 514 Dynamic code evaluation 515 The "eval" method and the "Function(...string)" constructor MUST NOT be 516 used outside of code loaders. These features are potentially dangerous 517 and simply do not work in CSP environments. 518 519 Automatic semicolon insertion 520 Always terminate statements with semicolons, except for function and 521 class declarations. 522 523 Non-standard features 524 Non-standard features MUST NOT be used. This includes old features that 525 have been removed, new features that are not yet standardized or 526 proprietary that are only implemented in some JavaScript environments. 527 These features are only allowed if the code being written is intended 528 for only that environment. 529 530 Wrapper objects for primitive types 531 Never use the "new" keyword on primitive object wrappers nor include 532 them in type annotations. The wrappers MAY be called as functions for 533 coercing (which is preferred over using "+" or concatenating the empty 534 string) or creating Symbols. 535 536 537 538 539 540 Bron [Page 9] 541 SPEC 0001 JavaScript Styling August 2018 542 543 4. Naming 544 545 4.1. Rules for all identifiers 546 547 Identifiers MUST use only ASCII letters, digits, underscores and the 548 dollar sign. 549 550 Give as descriptive a name as possible, within reason. Do not worry about 551 saving horizontal space as it is far more important to make your code 552 immediately understandable by a new reader. Do not use abbreviations that 553 are ambiguous or unfamiliar to readers outside your project and do not 554 abbreviate by deleting letters within a word. 555 556 4.2. Rules by identifier type 557 558 Package names ................................................. kebab-case 559 Class names ............................................... UpperCamelCase 560 Method names .............................................. lowerCamelCase 561 Enum names ................................................ UpperCamelCase 562 Constant names ...................................... SCREAMING_SNAKE_CASE 563 Non-constant field names .................................. lowerCamelCase 564 Parameter names ........................................... lowerCamelCase 565 Local variable names ...................................... lowerCamelCase 566 Template parameter names ............................ SCREAMING_SNAKE_CASE 567 568 5. JSDoc 569 570 5.1. General form 571 572 JSDoc is a generic docblock (/**) with a body as defined here. JSDoc is 573 either multi-line or single-line, where the single-line version MUST 574 follow the parameter or field section of the multi-line version. 575 576 There are many tools which extract metadata from JSDoc comments to perform 577 code validation and optimization. As such, these comments MUST be 578 well-formed. 579 580 A JSDoc comment can contain the following sections, which are described in 581 5.2. through 5.4.: 582 - Summary 583 - Description 584 - Tags 585 586 5.2. Summary 587 588 The summary is a one-line string used to give an impression of the 589 function of the documented element. This can be used in overviews to allow 590 the user to skim the documentation in search of the required template. 591 592 593 594 595 596 597 598 599 600 Bron [Page 10] 601 SPEC 0001 JavaScript Styling August 2018 602 603 5.3. Description 604 605 The description contains concise information about the function of the 606 documented element. The description MUST be in Markdown markup to apply 607 styling. 608 609 The following list has examples of types of information that can be 610 contained in a description: 611 - Explanation of algorithms 612 - Code examples 613 - Array specification 614 - Relation to other elements 615 - License information (in the case of file documentation) 616 617 Descriptions can also contain inline tags. These are special annotations 618 that can be substituted for a specialized type of information (such as 619 {@link}). Inline tags MUST always be surrounded by braces. 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 Bron [Page 11] 661 SPEC 0001 JavaScript Styling August 2018 662 663 5.4. Tags 664 665 Tags represent metadata with which IDEs, external tooling or even the 666 application itself know how to interpret an element. 667 668 5.4.1. JSDoc tag reference 669 670 The following tags are common and well supported by various 671 documentation generation tools (such as JsDossier) for purely 672 documentation purposes. 673 674 Tag Description 675 676 @author Document the author of a file or the owner of a 677 @owner test, generally only used in the @fileoverview comment. 678 Not recommended. 679 680 @bug Indicates what bugs the given test function regression 681 tests. Multiple bugs should each have their own @bug 682 line, to make searching for regression tests as easy as 683 possible. 684 685 @see Reference a lookup to another class function or method, 686 global function, file or URL. 687 688 @param Indicates the type of a function or method parameter, 689 optionally adding a description to further explain what 690 the described parameter does. 691 692 @return Indicates the return type of a function or method, 693 optionally adding a description to further explain what 694 the return value contains. 695 696 @type Indicate the documented element's type. 697 698 @const Describes the documented element is a constant variable, 699 that it MUST NOT be reassigned later. 700 701 @private Describes the documented element is private and care MUST 702 be taken to not expose the element to scopes other than 703 the one it is declared in. 704 705 @this Indicates the documented element uses the "this" keyword 706 and SHOULD be handled with care in relation to it's 707 context. 708 709 @override Indicates the documented method overrides the 710 equally-named super class method. 711 712 @deprecated Indicates the documented element is deprecated and this 713 SHOULD not be used in new code. 714 715 716 717 718 719 720 Bron [Page 12] 721 SPEC 0001 JavaScript Styling August 2018 722 723 5.5. Line wrapping 724 725 Line-wrapped block texts MUST be indented four spaces or be aligned with 726 the start of the text when it's a comment on a tag. 727 728 Wrapped description text SHOULD be lined up with the description on 729 previous lines. 730 731 5.6. Top/file-level comments 732 733 A file MAY have a top-level overview. A copyright notice and author 734 information are optional. File overviews are recommended whenever a file 735 consists of more than a single class definition. The top level comment is 736 designed to orient readers unfamiliar with the code to what is in this 737 file. If present, it MAY provide a description of the file's contents and 738 any dependencies or compatibility information. Line wrapping MUST follow 739 the rules defined in section 5.5. 740 741 5.7. Class comments 742 743 Classes, interfaces and records MUST be documented with a description and 744 any template parameters, implemented interfaces and other appropriate 745 tags. The class description SHOULD provide the reader with enough 746 information to know how and when to use the class, as wel as any 747 additional considerations necessary to correctly use the class. Textual 748 descriptions MAY be omitted on the constructor. 749 750 5.8. Enum and typedef comments 751 752 Enums and typedefs MUST be documented. Public enums and typedefs MUST have 753 a non-empty description. Individual enum items may be documented with a 754 JSDoc comment on the preceding line. 755 756 5.9. Method and function comments 757 758 Parameter and return types MUST be documented. The "this" type should be 759 documented when necessary. Method, parameter and return descriptions (but 760 not types) MAY be omitted if they are obvious from the rest of the 761 method's JSDoc or from it's signature. Method descriptions SHOULD start 762 with a sentence written in the third person declarative voice (a.k.a. the 763 summary). 764 765 If a method overrides a superclass method, it must include an @override 766 annotation. Overridden methods must include all @param and @return 767 annotations if any types are refined, but SHOULD emit them if the types 768 are all the same. 769 770 Anonymous functions do not require JSDoc, though parameters may be 771 specified inline if the automatic type inference is insufficient. 772 773 774 775 776 777 778 779 780 Bron [Page 13] 781 SPEC 0001 JavaScript Styling August 2018 782 783 5.10. Property comments 784 785 Property types must be documented. The description may be omitted for 786 private properties, if name and type provide enough documentation for 787 understanding the code. 788 789 Publicly exported constants are commented the same way as properties. 790 Explicit types may be omitted for @const properties initialized from an 791 expression with an obviously known type. 792 793 5.11. Nullability 794 795 When defining the type of a parameter or other element, nullability SHOULD 796 be indicated by either "!" or "?" as a prefix of the type for non-null and 797 nullable, respectively. Primitive types are nullable by default but cannot 798 be immediately distinguished from a name that is typed to a 799 non-null-by-default type. As such, all types except primitives and record 800 literals SHOULD be annotated explicitly with either "?" or "!" to indicate 801 whether they are nullable or not. 802 803 5.12. Template parameter types 804 805 Whenever possible, one SHOULD specify template parameters when dealing 806 with elements which by default contain other elements, such as Objects, 807 Arrays or a Promise. 808 809 Objects MUST NOT specify template parameters when used as a hierarchy 810 instead of a map-like structure. 811 812 6. Policies 813 814 6.1. Unspecified styling 815 816 For any style question that isn't settled definitively by this 817 specification, one SHOULD follow the code style of the rest of the file. 818 If that doesn't resolve the question, consider emulating the other files 819 in the same package. If that still does not resolve the question, follow 820 the rules set by standardjs. 821 822 As a rule of thumb: be consistent throughout the package. 823 824 6.2. Deprecation 825 826 Mark deprecated methods, classes, interfaces or functions with @deprecated 827 annotations. A deprecation comment MUST include simple, clear directions 828 for people to fix their call sites. 829 830 6.3. Code not in Finwo Style 831 832 You will occasionally encounter files in your codebase that are not in 833 proper Finwo Style. These may have come from an acquisition, or may have 834 been written before Finwo Style took a position on some issue, or may be 835 in non-Finwo Style for any other reason. 836 837 838 839 840 Bron [Page 14] 841 SPEC 0001 JavaScript Styling August 2018 842 843 6.3.1. Reformatting existing code 844 845 When working on the file, only reformat the functions and/or methods 846 you change instead of the whole file. If significant changes are being 847 made to a file, it is expected that the file will be in Finwo Style. 848 849 6.3.2. Newly added code 850 851 Brand new files MUST use Finwo style, regardless of style choices of 852 other files in the same package. When adding new code to a file that is 853 not in Finwo Style, reformatting the existing code first is 854 recommended, subject to the advice in section 6.3.1. 855 856 If this reformatting is not done, the new code should be as consistent 857 as possible with existing code in the same file, but MUST not break any 858 rules of this specification. 859 860 6.4. Local style rules 861 862 Teams and projects may adopt additional style rules beyond those in this 863 document, but must accept that cleanup changes may not abide by these 864 additional rules, and must not block such cleanup changes due to violating 865 any additional rules. Beware of excessive rules which serve no purpose. 866 The style guide does not seek to define style in every possible scenario 867 and neither should you. 868 869 6.5. Generated code 870 871 Source code generate by any build process is not required to be in Finwo 872 Style. However, any generated identifiers that will by referenced from 873 hand-written code must follow the naming requirements. As a special 874 exception, such identifiers are allowed to contain underscores, which may 875 help to avoid conflicts with hand-written identifiers. 876 877 6.6. Third-party code 878 879 This style specification does not apply to third-party code used within 880 the package. When working on third-party code embedded in the package, 881 section 6.3 applies. 882 883 When working on third-party code which is not embedded in the package, you 884 MUST follow the style guide supplied by that project if available. 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 Bron [Page 15] 901 SPEC 0001 JavaScript Styling August 2018 902 903 7. Informative resources 904 905 [JSGUIDE] Google JavaScript Style Guide 906 https://google.github.io/styleguide/jsguide 907 908 [STANDARDJS] StandardJS standard style 909 https://standardjs.com/rules 910 911 [kebab-case] Special case styles 912 https://en.wikipedia.org/wiki/Kebab_case 913 914 [camel-case] Camel case 915 https://en.wikipedia.org/wiki/Camel_case 916 917 [SCREAMING_SNAKE_CASE] Snake case 918 https://en.wikipedia.org/wiki/Snake_case 919 920 [RFC20] ASCII format for Network Interchange 921 Vint Cerf 922 https://tools.ietf.org/html/rfc20 923 924 [RFC2119] RFC Key Words 925 S. Bradner 926 https://tools.ietf.org/html/rfc2119 927 928 [RFC3629] UTF-8 929 F. Yergeau 930 https://tools.ietf.org/html/rfc3629 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 Bron [Page 16] 961 SPEC 0001 JavaScript Styling August 2018 962 963 8. Author information 964 965 Name ....... Robin Bron 966 Nickname ... Finwo 967 EMail ...... robin@finwo.nl 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 Bron [Page 17]