| <div class="numbered"></div> | |
| # TS/JS Style Guide | |
| This guide is based on the internal Google TypeScript style guide, but it has | |
| been slightly adjusted to remove Google-internal sections. Google's internal | |
| environment has different constraints on TypeScript than you might find outside | |
| of Google. The advice here is specifically useful for people authoring code they | |
| intend to import into Google, but otherwise may not apply in your external | |
| environment. | |
| There is no automatic deployment process for this version as it's pushed | |
| on-demand by volunteers. | |
| <!-- mdformat off --> | |
| * TOC | |
| {:toc} | |
| <!-- mdformat on --> | |
| <div class="numbered"></div> | |
| <a id="introduction"></a> | |
| ## Introduction | |
| <div class="numbered"></div> | |
| <a id="terminology-notes"></a> | |
| ### Terminology notes | |
| This Style Guide uses [RFC 2119](https://tools.ietf.org/html/rfc2119) | |
| terminology when using the phrases *must*, *must not*, *should*, *should not*, | |
| and *may*. The terms *prefer* and *avoid* correspond to *should* and *should | |
| not*, respectively. Imperative and declarative statements are prescriptive and | |
| correspond to *must*. | |
| <div class="numbered"></div> | |
| <a id="guide-notes"></a> | |
| ### Guide notes | |
| All examples given are **non-normative** and serve only to illustrate the | |
| normative language of the style guide. That is, while the examples are in Google | |
| Style, they may not illustrate the *only* stylish way to represent the code. | |
| Optional formatting choices made in examples must not be enforced as rules. | |
| <div class="numbered"></div> | |
| <a id="source-file-basics"></a> | |
| ## Source file basics | |
| <a id="file-encoding"></a> | |
| <div class="numbered"></div> | |
| <a id="file-encoding-utf-8"></a> | |
| ### File encoding: UTF-8 | |
| Source files are encoded in **UTF-8**. | |
| <a id="special-characters"></a> | |
| <div class="numbered"></div> | |
| <a id="whitespace-characters"></a> | |
| #### Whitespace characters | |
| Aside from the line terminator sequence, the ASCII horizontal space character | |
| (0x20) is the only whitespace character that appears anywhere in a source file. | |
| This implies that all other whitespace characters in string literals are | |
| escaped. | |
| <div class="numbered"></div> | |
| <a id="special-escape-sequences"></a> | |
| #### Special escape sequences | |
| For any character that has a special escape sequence (`\'`, `\"`, `\\ `, `\b`, | |
| `\f`, `\n`, `\r`, `\t`, `\v`), that sequence is used rather than the | |
| corresponding numeric escape (e.g `\x0a`, `\u000a`, or `\u{a}`). Legacy octal | |
| escapes are never used. | |
| <div class="numbered"></div> | |
| <a id="non-ascii-characters"></a> | |
| #### Non-ASCII characters | |
| For the remaining non-ASCII characters, use the actual Unicode character (e.g. | |
| `∞`). For non-printable characters, the equivalent hex or Unicode escapes (e.g. | |
| `\u221e`) can be used along with an explanatory comment. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Perfectly clear, even without a comment. | |
| const units = 'μs'; | |
| // Use escapes for non-printable characters. | |
| const output = '\ufeff' + content; // byte order mark | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| // Hard to read and prone to mistakes, even with the comment. | |
| const units = '\u03bcs'; // Greek letter mu, 's' | |
| // The reader has no idea what this is. | |
| const output = '\ufeff' + content; | |
| ``` | |
| <a id="modules"></a> | |
| <a id="source-organization"></a> | |
| <div class="numbered"></div> | |
| <a id="source-file-structure"></a> | |
| ## Source file structure | |
| Files consist of the following, **in order**: | |
| 1. Copyright information, if present | |
| 2. JSDoc with `@fileoverview` and/or other file-level JSDoc tags if present. | |
| 3. Imports, if present | |
| 4. The file’s implementation | |
| **Exactly one blank line** separates each section that is present. | |
| <div class="numbered"></div> | |
| <a id="file-copyright"></a> | |
| ### Copyright information | |
| If license or copyright information is necessary in a file, add it in a JSDoc at | |
| the top of the file. | |
| <a id="file-fileoverview"></a> | |
| <a id="jsdoc-top-file-level-comments"></a> | |
| <div class="numbered"></div> | |
| <a id="fileoverview"></a> | |
| ### `@fileoverview` JSDoc | |
| A file may have a top-level `@fileoverview` JSDoc. If present, it may provide a | |
| description of the file's content, its uses, or information about its | |
| dependencies. Wrapped lines are not indented. | |
| Example: | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** | |
| * @fileoverview Description of file. Lorem ipsum dolor sit amet, consectetur | |
| * adipiscing elit, sed do eiusmod tempor incididunt. | |
| */ | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="imports"></a> | |
| ### Imports | |
| There are four variants of import statements in ES6 and TypeScript: | |
| <!-- mdformat off --> | |
| | Import type | Example | Use for | | |
| | ---------------------------- | -------------------------------- | ------------------ | | |
| | module[^module_import] | `import * as foo from '...';` | TypeScript imports | | |
| | named[^destructuring_import] | `import {SomeThing} from '...';` | TypeScript imports | | |
| | default | `import SomeThing from '...';` | Only for other external code that requires them | | |
| | side-effect | `import '...';` | Only to import libraries for their side-effects on load (such as custom elements) | | |
| <!-- mdformat on --> | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Good: choose between two options as appropriate (see below). | |
| import * as ng from '@angular/core'; | |
| import {Foo} from './foo'; | |
| // Only when needed: default imports. | |
| import Button from 'Button'; | |
| // Sometimes needed to import libraries for their side effects: | |
| import 'jasmine'; | |
| import '@polymer/paper-button'; | |
| ``` | |
| [^module_import]: Namespace imports are often called 'module imports' | |
| [^destructuring_import]: named imports are sometimes called 'destructuring | |
| imports' because they use similar syntax to destructuring assignments. | |
| <div class="numbered"></div> | |
| <a id="import-paths"></a> | |
| #### Import paths | |
| TypeScript code *must* use paths to import other TypeScript code. Paths *may* be | |
| relative, i.e. starting with `.` or `..`, or rooted at the base directory, e.g. | |
| `root/path/to/file`. | |
| Code *should* use relative imports (`./foo`) rather than absolute imports | |
| `path/to/foo` when referring to files within the same (logical) project as this | |
| allows to move the project around without introducing changes in these imports. | |
| Consider limiting the number of parent steps (`../../../`) as those can make | |
| module and path structures hard to understand. | |
| <div class='goodcode'></div> | |
| ```ts | |
| import {Symbol1} from 'path/from/root'; | |
| import {Symbol2} from '../parent/file'; | |
| import {Symbol3} from './sibling'; | |
| ``` | |
| <!-- Keep the previous id for backwards compatibility with links. --> | |
| <a id="module-versus-destructuring-import"></a> | |
| <div class="numbered"></div> | |
| <a id="namespace-versus-named-imports"></a> | |
| #### Namespace versus named imports | |
| Both namespace and named imports can be used. | |
| Prefer named imports for symbols used frequently in a file or for symbols that | |
| have clear names, for example Jasmine's `describe` and `it`. Named imports can | |
| be aliased to clearer names as needed with `as`. | |
| Prefer namespace imports when using many different symbols from large APIs. A | |
| namespace import, despite using the `*` character, is not comparable to a | |
| "wildcard" import as seen in other languages. Instead, namespace imports give a | |
| name to all the exports of a module, and each exported symbol from the module | |
| becomes a property on the module name. Namespace imports can aid readability for | |
| exported symbols that have common names like `Model` or `Controller` without the | |
| need to declare aliases. | |
| <div class='badcode'></div> | |
| ```ts | |
| // Bad: overlong import statement of needlessly namespaced names. | |
| import {Item as TableviewItem, Header as TableviewHeader, Row as TableviewRow, | |
| Model as TableviewModel, Renderer as TableviewRenderer} from './tableview'; | |
| let item: TableviewItem|undefined; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Better: use the module for namespacing. | |
| import * as tableview from './tableview'; | |
| let item: tableview.Item|undefined; | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| import * as testing from './testing'; | |
| // Bad: The module name does not improve readability. | |
| testing.describe('foo', () => { | |
| testing.it('bar', () => { | |
| testing.expect(null).toBeNull(); | |
| testing.expect(undefined).toBeUndefined(); | |
| }); | |
| }); | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Better: give local names for these common functions. | |
| import {describe, it, expect} from './testing'; | |
| describe('foo', () => { | |
| it('bar', () => { | |
| expect(null).toBeNull(); | |
| expect(undefined).toBeUndefined(); | |
| }); | |
| }); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="jspb-import-by-path"></a> | |
| ##### Special case: Apps JSPB protos | |
| Apps JSPB protos must use named imports, even when it leads to long import | |
| lines. | |
| This rule exists to aid in build performance and dead code elimination since | |
| often `.proto` files contain many `message`s that are not all needed together. | |
| By leveraging destructured imports the build system can create finer grained | |
| dependencies on Apps JSPB messages while preserving the ergonomics of path based | |
| imports. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Good: import the exact set of symbols you need from the proto file. | |
| import {Foo, Bar} from './foo.proto'; | |
| function copyFooBar(foo: Foo, bar: Bar) {...} | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="renaming-imports"></a> | |
| #### Renaming imports | |
| Code *should* fix name collisions by using a namespace import or renaming the | |
| exports themselves. Code *may* rename imports | |
| (`import {SomeThing as SomeOtherThing}`) if needed. | |
| Three examples where renaming can be helpful: | |
| 1. If it's necessary to avoid collisions with other imported symbols. | |
| 2. If the imported symbol name is generated. | |
| 3. If importing symbols whose names are unclear by themselves, renaming can | |
| improve code clarity. For example, when using RxJS the `from` function might | |
| be more readable when renamed to `observableFrom`. | |
| <div class="numbered"></div> | |
| <a id="exports"></a> | |
| ### Exports | |
| Use named exports in all code: | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Use named exports: | |
| export class Foo { ... } | |
| ``` | |
| Do not use default exports. This ensures that all imports follow a uniform | |
| pattern. | |
| <div class='badcode'></div> | |
| ```ts | |
| // Do not use default exports: | |
| export default class Foo { ... } // BAD! | |
| ``` | |
| Why? | |
| Default exports provide no canonical name, which makes central maintenance | |
| difficult with relatively little benefit to code owners, including potentially | |
| decreased readability: | |
| <div class='badcode'></div> | |
| ```ts | |
| import Foo from './bar'; // Legal. | |
| import Bar from './bar'; // Also legal. | |
| ``` | |
| Named exports have the benefit of erroring when import statements try to import | |
| something that hasn't been declared. In `foo.ts`: | |
| <div class='badcode'></div> | |
| ```ts | |
| const foo = 'blah'; | |
| export default foo; | |
| ``` | |
| And in `bar.ts`: | |
| <div class='badcode'></div> | |
| ```ts | |
| import {fizz} from './foo'; | |
| ``` | |
| Results in `error TS2614: Module '"./foo"' has no exported member 'fizz'.` While | |
| `bar.ts`: | |
| <div class='badcode'></div> | |
| ```ts | |
| import fizz from './foo'; | |
| ``` | |
| Results in `fizz === foo`, which is probably unexpected and difficult to debug. | |
| Additionally, default exports encourage people to put everything into one big | |
| object to namespace it all together: | |
| <div class='badcode'></div> | |
| ```ts | |
| export default class Foo { | |
| static SOME_CONSTANT = ... | |
| static someHelpfulFunction() { ... } | |
| ... | |
| } | |
| ``` | |
| With the above pattern, we have file scope, which can be used as a namespace. We | |
| also have a perhaps needless second scope (the class `Foo`) that can be | |
| ambiguously used as both a type and a value in other files. | |
| Instead, prefer use of file scope for namespacing, as well as named exports: | |
| <div class='goodcode'></div> | |
| ```ts | |
| export const SOME_CONSTANT = ... | |
| export function someHelpfulFunction() | |
| export class Foo { | |
| // only class stuff here | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="export-visibility"></a> | |
| #### Export visibility | |
| TypeScript does not support restricting the visibility for exported symbols. | |
| Only export symbols that are used outside of the module. Generally minimize the | |
| exported API surface of modules. | |
| <div class="numbered"></div> | |
| <a id="mutable-exports"></a> | |
| #### Mutable exports | |
| Regardless of technical support, mutable exports can create hard to understand | |
| and debug code, in particular with re-exports across multiple modules. One way | |
| to paraphrase this style point is that `export let` is not allowed. | |
| <div class='badcode'></div> | |
| ```ts | |
| export let foo = 3; | |
| // In pure ES6, foo is mutable and importers will observe the value change after a second. | |
| // In TS, if foo is re-exported by a second file, importers will not see the value change. | |
| window.setTimeout(() => { | |
| foo = 4; | |
| }, 1000 /* ms */); | |
| ``` | |
| If one needs to support externally accessible and mutable bindings, they | |
| *should* instead use explicit getter functions. | |
| <div class='goodcode'></div> | |
| ```ts | |
| let foo = 3; | |
| window.setTimeout(() => { | |
| foo = 4; | |
| }, 1000 /* ms */); | |
| // Use an explicit getter to access the mutable export. | |
| export function getFoo() { return foo; }; | |
| ``` | |
| For the common pattern of conditionally exporting either of two values, first do | |
| the conditional check, then the export. Make sure that all exports are final | |
| after the module's body has executed. | |
| <div class='goodcode'></div> | |
| ```ts | |
| function pickApi() { | |
| if (useOtherApi()) return OtherApi; | |
| return RegularApi; | |
| } | |
| export const SomeApi = pickApi(); | |
| ``` | |
| <a id="static-containers"></a> | |
| <div class="numbered"></div> | |
| <a id="container-classes"></a> | |
| #### Container classes | |
| Do not create container classes with static methods or properties for the sake | |
| of namespacing. | |
| <div class='badcode'></div> | |
| ```ts | |
| export class Container { | |
| static FOO = 1; | |
| static bar() { return 1; } | |
| } | |
| ``` | |
| Instead, export individual constants and functions: | |
| <div class='goodcode'></div> | |
| ```ts | |
| export const FOO = 1; | |
| export function bar() { return 1; } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="import-export-type"></a> | |
| ### Import and export type | |
| <div class="numbered"></div> | |
| <a id="import-type"></a> | |
| #### Import type | |
| You may use `import type {...}` when you use the imported symbol only as a type. | |
| Use regular imports for values: | |
| <div class='goodcode'></div> | |
| ```ts | |
| import type {Foo} from './foo'; | |
| import {Bar} from './foo'; | |
| import {type Foo, Bar} from './foo'; | |
| ``` | |
| Why? | |
| The TypeScript compiler automatically handles the distinction and does not | |
| insert runtime loads for type references. So why annotate type imports? | |
| The TypeScript compiler can run in 2 modes: | |
| - In development mode, we typically want quick iteration loops. The compiler | |
| transpiles to JavaScript without full type information. This is much faster, | |
| but requires `import type` in certain cases. | |
| - In production mode, we want correctness. The compiler type checks everything | |
| and ensures `import type` is used correctly. | |
| Note: If you need to force a runtime load for side effects, use `import '...';`. | |
| See [the imports](#imports). | |
| <div class="numbered"></div> | |
| <a id="export-type"></a> | |
| #### Export type | |
| Use `export type` when re-exporting a type, e.g.: | |
| <div class='goodcode'></div> | |
| ```ts | |
| export type {AnInterface} from './foo'; | |
| ``` | |
| Why? | |
| `export type` is useful to allow type re-exports in file-by-file transpilation. | |
| See | |
| [`isolatedModules` docs](https://www.typescriptlang.org/tsconfig#exports-of-non-value-identifiers). | |
| `export type` might also seem useful to avoid ever exporting a value symbol for | |
| an API. However it does not give guarantees, either: downstream code might still | |
| import an API through a different path. A better way to split & guarantee type | |
| vs value usages of an API is to actually split the symbols into e.g. | |
| `UserService` and `AjaxUserService`. This is less error prone and also better | |
| communicates intent. | |
| <div class="numbered"></div> | |
| <a id="dynamic-import-type"></a> | |
| #### Dynamic `import()` type | |
| Do not use the `import()` function inside type annotations. | |
| <div class='badcode'></div> | |
| ```ts | |
| let f: import('./foo').Foo; | |
| ``` | |
| If you need to ensure that the import is always elided from the generated | |
| JavaScript, use `import type` instead. | |
| <div class='goodcode'></div> | |
| ```ts | |
| import type {Foo} from './foo'; | |
| ``` | |
| <a id="namespaces-vs-modules"></a> | |
| <div class="numbered"></div> | |
| <a id="use-modules-not-namespaces"></a> | |
| #### Use modules not namespaces | |
| TypeScript supports two methods to organize code: *namespaces* and *modules*, | |
| but namespaces are disallowed. That is, your code *must* refer to code in other | |
| files using imports and exports of the form `import {foo} from 'bar';` | |
| Your code *must not* use the `namespace Foo { ... }` construct. `namespace`s | |
| *may* only be used when required to interface with external, third party code. | |
| To semantically namespace your code, use separate files. | |
| Code *must not* use `require` (as in `import x = require('...');`) for imports. | |
| Use ES6 module syntax. | |
| <div class='badcode'></div> | |
| ```ts | |
| // Bad: do not use namespaces: | |
| namespace Rocket { | |
| function launch() { ... } | |
| } | |
| // Bad: do not use <reference> | |
| /// <reference path="..."/> | |
| // Bad: do not use require() | |
| import x = require('mydep'); | |
| ``` | |
| > NB: TypeScript `namespace`s used to be called internal modules and used to use | |
| > the `module` keyword in the form `module Foo { ... }`. Don't use that either. | |
| > Always use ES6 imports. | |
| <a id="language-rules"></a> | |
| <div class="numbered"></div> | |
| <a id="language-features"></a> | |
| ## Language features | |
| This section delineates which features may or may not be used, and any | |
| additional constraints on their use. | |
| Language features which are not discussed in this style guide *may* be used with | |
| no recommendations of their usage. | |
| <a id="features-local-variable-declarations"></a> | |
| <div class="numbered"></div> | |
| <a id="local-variable-declarations"></a> | |
| ### Local variable declarations | |
| <a id="variables"></a> | |
| <a id="features-use-const-and-let"></a> | |
| <div class="numbered"></div> | |
| <a id="use-const-and-let"></a> | |
| #### Use const and let | |
| Always use `const` or `let` to declare variables. Use `const` by default, unless | |
| a variable needs to be reassigned. Never use `var`. | |
| <div class='goodcode'></div> | |
| ```ts | |
| const foo = otherValue; // Use if "foo" never changes. | |
| let bar = someValue; // Use if "bar" is ever assigned into later on. | |
| ``` | |
| `const` and `let` are block scoped, like variables in most other languages. | |
| `var` in JavaScript is function scoped, which can cause difficult to understand | |
| bugs. Don't use it. | |
| <div class='badcode'></div> | |
| ```ts | |
| var foo = someValue; // Don't use - var scoping is complex and causes bugs. | |
| ``` | |
| Variables *must not* be used before their declaration. | |
| <a id="features-one-variable-per-declaration"></a> | |
| <div class="numbered"></div> | |
| <a id="one-variable-per-declaration"></a> | |
| #### One variable per declaration | |
| Every local variable declaration declares only one variable: declarations such | |
| as <code class="badcode">let a = 1, b = 2;</code> are not used. | |
| <a id="features-array-literals"></a> | |
| <div class="numbered"></div> | |
| <a id="array-literals"></a> | |
| ### Array literals | |
| <a id="features-arrays-ctor"></a> | |
| <div class="numbered"></div> | |
| <a id="array-constructor"></a> | |
| #### Do not use the `Array` constructor | |
| *Do not* use the `Array()` constructor, with or without `new`. It has confusing | |
| and contradictory usage: | |
| <!-- | |
| Silencing a CommonTypos warning for incorrect array constructor usage. | |
| common_typos_disable | |
| --> | |
| <div class='badcode'></div> | |
| ```ts | |
| const a = new Array(2); // [undefined, undefined] | |
| const b = new Array(2, 3); // [2, 3]; | |
| ``` | |
| <!-- common_typos_enable --> | |
| Instead, always use bracket notation to initialize arrays, or `from` to | |
| initialize an `Array` with a certain size: | |
| <div class='goodcode'></div> | |
| ```ts | |
| const a = [2]; | |
| const b = [2, 3]; | |
| // Equivalent to Array(2): | |
| const c = []; | |
| c.length = 2; | |
| // [0, 0, 0, 0, 0] | |
| Array.from<number>({length: 5}).fill(0); | |
| ``` | |
| <a id="features-arrays-non-numeric-properties"></a> | |
| <div class="numbered"></div> | |
| <a id="do-not-define-properties-on-arrays"></a> | |
| #### Do not define properties on arrays | |
| Do not define or use non-numeric properties on an array (other than `length`). | |
| Use a `Map` (or `Object`) instead. | |
| <a id="features-arrays-destructuring"></a> | |
| <div class="numbered"></div> | |
| <a id="array-destructuring"></a> | |
| #### Array destructuring | |
| Array literals may be used on the left-hand side of an assignment to perform | |
| destructuring (such as when unpacking multiple values from a single array or | |
| iterable). A final "rest" element may be included (with no space between the | |
| `...` and the variable name). Elements should be omitted if they are unused. | |
| <div class='goodcode'></div> | |
| ```ts | |
| const [a, b, c, ...rest] = generateResults(); | |
| let [, b,, d] = someArray; | |
| ``` | |
| Destructuring may also be used for function parameters. Always specify `[]` as | |
| the default value if a destructured array parameter is optional, and provide | |
| default values on the left hand side: | |
| <div class='goodcode'></div> | |
| ```ts | |
| function destructured([a = 4, b = 2] = []) { … } | |
| ``` | |
| Disallowed: | |
| <div class='badcode'></div> | |
| ```ts | |
| function badDestructuring([a, b] = [4, 2]) { … } | |
| ``` | |
| Tip: For (un)packing multiple values into a function’s parameter or return, | |
| prefer object destructuring to array destructuring when possible, as it allows | |
| naming the individual elements and specifying a different type for each. | |
| <a id="features-object-literals"></a> | |
| <div class="numbered"></div> | |
| <a id="object-literals"></a> | |
| ### Object literals | |
| <a id="features-objects-ctor"></a> | |
| <div class="numbered"></div> | |
| <a id="object-constructor"></a> | |
| #### Do not use the `Object` constructor | |
| The `Object` constructor is disallowed. Use an object literal (`{}` or | |
| `{a: 0, b: 1, c: 2}`) instead. | |
| <div class="numbered"></div> | |
| <a id="iterating-objects"></a> | |
| #### Iterating objects | |
| Iterating objects with `for (... in ...)` is error prone. It will include | |
| enumerable properties from the prototype chain. | |
| Do not use unfiltered `for (... in ...)` statements: | |
| <div class='badcode'></div> | |
| ```ts | |
| for (const x in someObj) { | |
| // x could come from some parent prototype! | |
| } | |
| ``` | |
| Either filter values explicitly with an `if` statement, or use | |
| `for (... of Object.keys(...))`. | |
| <div class='goodcode'></div> | |
| ```ts | |
| for (const x in someObj) { | |
| if (!someObj.hasOwnProperty(x)) continue; | |
| // now x was definitely defined on someObj | |
| } | |
| for (const x of Object.keys(someObj)) { // note: for _of_! | |
| // now x was definitely defined on someObj | |
| } | |
| for (const [key, value] of Object.entries(someObj)) { // note: for _of_! | |
| // now key was definitely defined on someObj | |
| } | |
| ``` | |
| <a id="using-the-spread-operator"></a> | |
| <div class="numbered"></div> | |
| <a id="object-spread-syntax"></a> | |
| #### Using spread syntax | |
| Using spread syntax `{...bar}` is a convenient shorthand for creating a shallow | |
| copy of an object. When using spread syntax in object initialization, later | |
| values replace earlier values at the same key. | |
| <div class='goodcode'></div> | |
| ```ts | |
| const foo = { | |
| num: 1, | |
| }; | |
| const foo2 = { | |
| ...foo, | |
| num: 5, | |
| }; | |
| const foo3 = { | |
| num: 5, | |
| ...foo, | |
| } | |
| foo2.num === 5; | |
| foo3.num === 1; | |
| ``` | |
| Avoid spreading objects that have prototypes other than the Object prototype | |
| (e.g. class definitions, class instances, functions) as the behavior is | |
| unintuitive (only enumerable non-prototype properties are shallow-copied). | |
| <div class='badcode'></div> | |
| ```ts | |
| // Creates {0: 'a', 1: 'b', 2: 'c'} but has no length | |
| const fooStrings = ['a', 'b', 'c']; | |
| const ids = {...fooStrings}; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| const options = {foo: 1, bar: 2}; | |
| const extended = {...options, baz: 3}; | |
| ``` | |
| <a id="features-objects-computed-property-names"></a> | |
| <div class="numbered"></div> | |
| <a id="computed-property-names"></a> | |
| #### Computed property names | |
| Computed property names (e.g. `{['key' + foo()]: 42}`) are allowed, and are | |
| considered dict-style (quoted) keys (i.e., must not be mixed with non-quoted | |
| keys) unless the computed property is a | |
| [symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) | |
| (e.g. `[Symbol.iterator]`). | |
| <a id="features-objects-destructuring"></a> | |
| <div class="numbered"></div> | |
| <a id="object-destructuring"></a> | |
| #### Object destructuring | |
| Object destructuring patterns may be used on the left-hand side of an assignment | |
| to perform destructuring and unpack multiple values from a single object. | |
| Destructured objects may also be used as function parameters, but should be kept | |
| as simple as possible: a single level of unquoted shorthand properties. Deeper | |
| levels of nesting and computed properties may not be used in parameter | |
| destructuring. Specify any default values in the left-hand-side of the | |
| destructured parameter (`{str = 'some default'} = {}`, rather than | |
| <code class="badcode">{str} = {str: 'some default'}</code>), and if a | |
| destructured object is itself optional, it must default to `{}`. | |
| Example: | |
| <div class='goodcode'></div> | |
| ```ts | |
| interface Options { | |
| /** The number of times to do something. */ | |
| num?: number; | |
| /** A string to do stuff to. */ | |
| str?: string; | |
| } | |
| function destructured({num, str = 'default'}: Options = {}) {} | |
| ``` | |
| Disallowed: | |
| <div class='badcode'></div> | |
| ```ts | |
| function nestedTooDeeply({x: {num, str}}: {x: Options}) {} | |
| function nontrivialDefault({num, str}: Options = {num: 42, str: 'default'}) {} | |
| ``` | |
| <a id="formatting-class-literals"></a> | |
| <a id="features-classes"></a> | |
| <div class="numbered"></div> | |
| <a id="classes"></a> | |
| ### Classes | |
| <div class="numbered"></div> | |
| <a id="class-declarations"></a> | |
| #### Class declarations | |
| Class declarations *must not* be terminated with semicolons: | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| }; // Unnecessary semicolon | |
| ``` | |
| In contrast, statements that contain class expressions *must* be terminated with | |
| a semicolon: | |
| <div class='goodcode'></div> | |
| ```ts | |
| export const Baz = class extends Bar { | |
| method(): number { | |
| return this.x; | |
| } | |
| }; // Semicolon here as this is a statement, not a declaration | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| exports const Baz = class extends Bar { | |
| method(): number { | |
| return this.x; | |
| } | |
| } | |
| ``` | |
| It is neither encouraged nor discouraged to have blank lines separating class | |
| declaration braces from other class content: | |
| <div class='goodcode'></div> | |
| ```ts | |
| // No spaces around braces - fine. | |
| class Baz { | |
| method(): number { | |
| return this.x; | |
| } | |
| } | |
| // A single space around both braces - also fine. | |
| class Foo { | |
| method(): number { | |
| return this.x; | |
| } | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="no-ctor-only-members"></a> | |
| #### Don't create member variables only used in constructors | |
| If a variable is only used in the constructor, then it can be migrated to be a | |
| variable scoped to the constructor body, which will make your class more | |
| stateless and easier to reason about for future devs. | |
| Some classes have methods that are only called in the constructor and that | |
| update bits of class state that are only used during class construction. For the | |
| same reasons as above, these bits of class state should also be migrated to be | |
| constructor-local variables. | |
| <div class='badcode'></div> | |
| ```ts | |
| class MyClass { | |
| // BAD: onlyUsedInCtor is only used in the constructor and nowhere else after | |
| // class initialization. | |
| private readonly onlyUsedInCtor = ...; | |
| private readonly otherDataStructure = ...; | |
| constructor( | |
| // BAD: Services only used in the constructor but kept after ctor execution. | |
| private readonly serviceA: ServiceA, | |
| private readonly serviceB: ServiceB, | |
| private readonly serviceC: ServiceC, | |
| ) { | |
| this.computeThing( | |
| this.serviceA.getA(), this.serviceB.getB(), this.serviceC.getC(), | |
| ); | |
| this.otherDataStructure = computeOther(this.onlyUsedInCtor); | |
| } | |
| private computeThing(a: A, b: B, c: C) { | |
| this.onlyUsedInCtor = someFunctionOf(a, b, c); | |
| } | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| class MyClass { | |
| private readonly otherDataStructure = ...; | |
| constructor( | |
| // GOOD: Services only used in constructor and dropped after ctor finishes. | |
| serviceA: ServiceA, | |
| serviceB: ServiceB, | |
| serviceC: ServiceC, | |
| ) { | |
| // GOOD: onlyUsedInCtor is a constructor-local variable. | |
| const onlyUsedInCtor = | |
| someFunctionOf(serviceA.getA(), serviceB.getB(), serviceC.getC()); | |
| this.otherDataStructure = computeOther(onlyUsedInCtor); | |
| } | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="class-method-declarations"></a> | |
| #### Class method declarations | |
| Class method declarations *must not* use a semicolon to separate individual | |
| method declarations: | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| doThing() { | |
| console.log("A"); | |
| } | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| doThing() { | |
| console.log("A"); | |
| }; // <-- unnecessary | |
| } | |
| ``` | |
| Method declarations should be separated from surrounding code by a single blank | |
| line: | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| doThing() { | |
| console.log("A"); | |
| } | |
| getOtherThing(): number { | |
| return 4; | |
| } | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| doThing() { | |
| console.log("A"); | |
| } | |
| getOtherThing(): number { | |
| return 4; | |
| } | |
| } | |
| ``` | |
| <a id="features-classes-overriding-tostring"></a> | |
| <div class="numbered"></div> | |
| <a id="overriding-tostring"></a> | |
| ##### Overriding toString | |
| The `toString` method may be overridden, but must always succeed and never have | |
| visible side effects. | |
| Tip: Beware, in particular, of calling other methods from toString, since | |
| exceptional conditions could lead to infinite loops. | |
| <a id="features-classes-static-methods"></a> | |
| <div class="numbered"></div> | |
| <a id="static-methods"></a> | |
| #### Static methods | |
| <div class="numbered"></div> | |
| <a id="avoid-private-static-methods"></a> | |
| ##### Avoid private static methods | |
| Where it does not interfere with readability, prefer module-local functions over | |
| private static methods. | |
| <div class="numbered"></div> | |
| <a id="avoid-static-method-dynamic-dispatch"></a> | |
| ##### Do not rely on dynamic dispatch | |
| Code *should not* rely on dynamic dispatch of static methods. Static methods | |
| *should* only be called on the base class itself (which defines it directly). | |
| Static methods *should not* be called on variables containing a dynamic instance | |
| that may be either the constructor or a subclass constructor (and *must* be | |
| defined with `@nocollapse` if this is done), and *must not* be called directly | |
| on a subclass that doesn’t define the method itself. | |
| Disallowed: | |
| <div class='badcode'></div> | |
| ```ts | |
| // Context for the examples below (this class is okay by itself) | |
| class Base { | |
| /** @nocollapse */ static foo() {} | |
| } | |
| class Sub extends Base {} | |
| // Discouraged: don't call static methods dynamically | |
| function callFoo(cls: typeof Base) { | |
| cls.foo(); | |
| } | |
| // Disallowed: don't call static methods on subclasses that don't define it themselves | |
| Sub.foo(); | |
| // Disallowed: don't access this in static methods. | |
| class MyClass { | |
| static foo() { | |
| return this.staticField; | |
| } | |
| } | |
| MyClass.staticField = 1; | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="static-this"></a> | |
| ##### Avoid static `this` references | |
| Code *must not* use `this` in a static context. | |
| JavaScript allows accessing static fields through `this`. Different from other | |
| languages, static fields are also inherited. | |
| <div class='badcode'></div> | |
| ```ts | |
| class ShoeStore { | |
| static storage: Storage = ...; | |
| static isAvailable(s: Shoe) { | |
| // Bad: do not use `this` in a static method. | |
| return this.storage.has(s.id); | |
| } | |
| } | |
| class EmptyShoeStore extends ShoeStore { | |
| static storage: Storage = EMPTY_STORE; // overrides storage from ShoeStore | |
| } | |
| ``` | |
| Why? | |
| This code is generally surprising: authors might not expect that static fields | |
| can be accessed through the this pointer, and might be surprised to find that | |
| they can be overridden - this feature is not commonly used. | |
| This code also encourages an anti-pattern of having substantial static state, | |
| which causes problems with testability. | |
| <a id="disallowed-features-omitting-parents-with-new"></a> | |
| <a id="features-classes-constructors"></a> | |
| <div class="numbered"></div> | |
| <a id="constructors"></a> | |
| #### Constructors | |
| Constructor calls *must* use parentheses, even when no arguments are passed: | |
| <div class='badcode'></div> | |
| ```ts | |
| const x = new Foo; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| const x = new Foo(); | |
| ``` | |
| Omitting parentheses can lead to subtle mistakes. These two lines are not | |
| equivalent: | |
| <div class='goodcode'></div> | |
| ```js | |
| new Foo().Bar(); | |
| new Foo.Bar(); | |
| ``` | |
| It is unnecessary to provide an empty constructor or one that simply delegates | |
| into its parent class because ES2015 provides a default class constructor if one | |
| is not specified. However constructors with parameter properties, visibility | |
| modifiers or parameter decorators *should not* be omitted even if the body of | |
| the constructor is empty. | |
| <div class='badcode'></div> | |
| ```ts | |
| class UnnecessaryConstructor { | |
| constructor() {} | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| class UnnecessaryConstructorOverride extends Base { | |
| constructor(value: number) { | |
| super(value); | |
| } | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| class DefaultConstructor { | |
| } | |
| class ParameterProperties { | |
| constructor(private myService) {} | |
| } | |
| class ParameterDecorators { | |
| constructor(@SideEffectDecorator myService) {} | |
| } | |
| class NoInstantiation { | |
| private constructor() {} | |
| } | |
| ``` | |
| The constructor should be separated from surrounding code both above and below | |
| by a single blank line: | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| myField = 10; | |
| constructor(private readonly ctorParam) {} | |
| doThing() { | |
| console.log(ctorParam.getThing() + myField); | |
| } | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| myField = 10; | |
| constructor(private readonly ctorParam) {} | |
| doThing() { | |
| console.log(ctorParam.getThing() + myField); | |
| } | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="class-members"></a> | |
| #### Class members | |
| <div class="numbered"></div> | |
| <a id="private-fields"></a> | |
| ##### No #private fields | |
| Do not use private fields (also known as private identifiers): | |
| <div class='badcode'></div> | |
| ```ts | |
| class Clazz { | |
| #ident = 1; | |
| } | |
| ``` | |
| Instead, use TypeScript's visibility annotations: | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Clazz { | |
| private ident = 1; | |
| } | |
| ``` | |
| Why? | |
| Private identifiers cause substantial emit size and performance regressions when | |
| down-leveled by TypeScript, and are unsupported before ES2015. They can only be | |
| downleveled to ES2015, not lower. At the same time, they do not offer | |
| substantial benefits when static type checking is used to enforce visibility. | |
| <div class="numbered"></div> | |
| <a id="use-readonly"></a> | |
| ##### Use readonly | |
| Mark properties that are never reassigned outside of the constructor with the | |
| `readonly` modifier (these need not be deeply immutable). | |
| <div class="numbered"></div> | |
| <a id="parameter-properties"></a> | |
| ##### Parameter properties | |
| Rather than plumbing an obvious initializer through to a class member, use a | |
| TypeScript | |
| [parameter property](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties). | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| private readonly barService: BarService; | |
| constructor(barService: BarService) { | |
| this.barService = barService; | |
| } | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| constructor(private readonly barService: BarService) {} | |
| } | |
| ``` | |
| If the parameter property needs documentation, | |
| [use an `@param` JSDoc tag](#parameter-property-comments). | |
| <div class="numbered"></div> | |
| <a id="field-initializers"></a> | |
| ##### Field initializers | |
| If initializing a class member does not rely on a constructor parameter or a | |
| parameter property, initialize it where it's declared. This sometimes lets you | |
| drop the constructor entirely. | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| private readonly userList: string[]; | |
| constructor() { | |
| this.userList = []; | |
| } | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| private readonly userList: string[] = []; | |
| } | |
| ``` | |
| It is possible to reference parameter properties from field initializers due to | |
| the way TypeScript transpiles this pattern to JavaScript. This transpilation is | |
| changing to match JavaScript language semantics, and referencing a parameter | |
| property from a field initializer will become a TypeScript compiler error, so | |
| this pattern should be avoided. | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| // BAD: references a property (`this.state`) that will be | |
| // initialized after this field. | |
| private readonly userList = initializeUserList(this.state); | |
| constructor(private readonly state: InitialState) {} | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| // GOOD: this must be initialized in the constructor | |
| private readonly userList: string[]; | |
| // This might allow converting the parameter property into a normal | |
| // constructor parameter. | |
| constructor(state: InitialState) { | |
| this.userList = initializeUserList(state); | |
| } | |
| } | |
| ``` | |
| Tip: Properties should never be added to or removed from an instance after the | |
| constructor is finished, since it significantly hinders VMs’ ability to optimize | |
| classes' "shape". Optional fields that may be filled in later should be | |
| explicitly initialized to `undefined` to prevent later shape changes. | |
| <div class="numbered"></div> | |
| <a id="properties-used-outside-of-class-lexical-scope"></a> | |
| ##### Properties used outside of class lexical scope | |
| Properties used from outside the lexical scope of their containing class, *must | |
| not* use `private` visibility, as they are used outside of the lexical scope of | |
| their containing class. | |
| Exception: Angular component properties used only from a template are allowed to | |
| use `private` visibility. | |
| Use either `protected` or `public` as appropriate to the property in question. | |
| TypeScript code *must not* use `obj['foo']` to bypass the visibility of a | |
| property. | |
| Why? | |
| When a property is `private`, you are declaring to both automated systems and | |
| humans that the property accesses are scoped to the methods of the declaring | |
| class, and they will rely on that. For example, a check for unused code will | |
| flag a private property that appears to be unused, even if some other file | |
| manages to bypass the visibility restriction. | |
| Though it might appear that `obj['foo']` can bypass visibility in the TypeScript | |
| compiler, this pattern can be broken by rearranging the build rules, and also | |
| violates [optimization compatibility](#optimization-compatibility). | |
| <a id="features-classes-getters-and-setters"></a> | |
| <div class="numbered"></div> | |
| <a id="classes-getters-and-setters"></a> | |
| ##### Getters and setters | |
| Getters and setters, also known as accessors, for class members *may* be used. | |
| The getter method *must* be a | |
| [pure function](https://en.wikipedia.org/wiki/Pure_function) (i.e., result is | |
| consistent and has no side effects: getters *must not* change observable state). | |
| They are also useful as a means of restricting the visibility of internal or | |
| verbose implementation details (shown below). | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| constructor(private readonly someService: SomeService) {} | |
| get someMember(): string { | |
| return this.someService.someVariable; | |
| } | |
| set someMember(newValue: string) { | |
| this.someService.someVariable = newValue; | |
| } | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| nextId = 0; | |
| get next() { | |
| return this.nextId++; // Bad: getter changes observable state | |
| } | |
| } | |
| ``` | |
| If an accessor is used to hide a class property, the hidden property *may* be | |
| prefixed or suffixed with any whole word, like `internal` or `wrapped`. When | |
| using these private properties, access the value through the accessor whenever | |
| possible. At least one accessor for a property *must* be non-trivial: do not | |
| define "pass-through" accessors only for the purpose of hiding a property. | |
| Instead, make the property public (or consider making it `readonly` rather than | |
| just defining a getter with no setter). | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| private wrappedBar = ''; | |
| get bar() { | |
| return this.wrappedBar || 'bar'; | |
| } | |
| set bar(wrapped: string) { | |
| this.wrappedBar = wrapped.trim(); | |
| } | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| class Bar { | |
| private barInternal = ''; | |
| // Neither of these accessors have logic, so just make bar public. | |
| get bar() { | |
| return this.barInternal; | |
| } | |
| set bar(value: string) { | |
| this.barInternal = value; | |
| } | |
| } | |
| ``` | |
| Getters and setters *must not* be defined using `Object.defineProperty`, since | |
| this interferes with property renaming. | |
| <a id="features-classes-computed-properties"></a> | |
| <div class="numbered"></div> | |
| <a id="class-computed-properties"></a> | |
| ##### Computed properties | |
| Computed properties may only be used in classes when the property is a symbol. | |
| Dict-style properties (that is, quoted or computed non-symbol keys) are not | |
| allowed. A `[Symbol.iterator]` method should be defined for any classes that are | |
| logically iterable. Beyond this, `Symbol` should be used sparingly. | |
| Tip: be careful of using any other built-in symbols (e.g. | |
| `Symbol.isConcatSpreadable`) as they are not polyfilled by the compiler and will | |
| therefore not work in older browsers. | |
| <div class="numbered"></div> | |
| <a id="visibility"></a> | |
| #### Visibility | |
| Restricting visibility of properties, methods, and entire types helps with | |
| keeping code decoupled. | |
| * Limit symbol visibility as much as possible. | |
| * Consider converting private methods to non-exported functions within the | |
| same file but outside of any class, and moving private properties into a | |
| separate, non-exported class. | |
| * TypeScript symbols are public by default. Never use the `public` modifier | |
| except when declaring non-readonly public parameter properties (in | |
| constructors). | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| public bar = new Bar(); // BAD: public modifier not needed | |
| constructor(public readonly baz: Baz) {} // BAD: readonly implies it's a property which defaults to public | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| bar = new Bar(); // GOOD: public modifier not needed | |
| constructor(public baz: Baz) {} // public modifier allowed | |
| } | |
| ``` | |
| See also [export visibility](#export-visibility). | |
| <div class="numbered"></div> | |
| <a id="disallowed-class-patterns"></a> | |
| #### Disallowed class patterns | |
| <a id="features-classes-prototypes"></a> | |
| <div class="numbered"></div> | |
| <a id="class-prototypes"></a> | |
| ##### Do not manipulate `prototype`s directly | |
| The `class` keyword allows clearer and more readable class definitions than | |
| defining `prototype` properties. Ordinary implementation code has no business | |
| manipulating these objects. Mixins and modifying the prototypes of built-in | |
| objects are explicitly forbidden. | |
| **Exception**: Framework code (such as Polymer, or Angular) may need to use | |
| `prototype`s, and should not resort to even-worse workarounds to avoid doing so. | |
| <a id="features-functions"></a> | |
| <div class="numbered"></div> | |
| <a id="functions"></a> | |
| ### Functions | |
| <div class="numbered"></div> | |
| <a id="terminology"></a> | |
| #### Terminology | |
| There are many different types of functions, with subtle distinctions between | |
| them. This guide uses the following terminology, which aligns with | |
| [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions): | |
| * "function declaration": a declaration (i.e. not an expression) using the | |
| `function` keyword | |
| * "function expression": an expression, typically used in an assignment or | |
| passed as a parameter, using the `function` keyword | |
| * "arrow function": an expression using the `=>` syntax | |
| * "block body": right hand side of an arrow function with braces | |
| * "concise body": right hand side of an arrow function without braces | |
| Methods and classes/constructors are not covered in this section. | |
| <div class="numbered"></div> | |
| <a id="function-declarations"></a> | |
| #### Prefer function declarations for named functions | |
| Prefer function declarations over arrow functions or function expressions when | |
| defining named functions. | |
| <div class='goodcode'></div> | |
| ```ts | |
| function foo() { | |
| return 42; | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| const foo = () => 42; | |
| ``` | |
| Arrow functions *may* be used, for example, when an explicit type annotation is | |
| required. | |
| <div class='goodcode'></div> | |
| ```ts | |
| interface SearchFunction { | |
| (source: string, subString: string): boolean; | |
| } | |
| const fooSearch: SearchFunction = (source, subString) => { ... }; | |
| ``` | |
| <a id="features-functions-nested-functions"></a> | |
| <div class="numbered"></div> | |
| <a id="nested-functions"></a> | |
| #### Nested functions | |
| Functions nested within other methods or functions *may* use function | |
| declarations or arrow functions, as appropriate. In method bodies in particular, | |
| arrow functions are preferred because they have access to the outer `this`. | |
| <a id="use-arrow-functions-in-expressions"></a> | |
| <div class="numbered"></div> | |
| <a id="function-expressions"></a> | |
| #### Do not use function expressions | |
| Do not use function expressions. Use arrow functions instead. | |
| <div class='goodcode'></div> | |
| ```ts | |
| bar(() => { this.doSomething(); }) | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| bar(function() { ... }) | |
| ``` | |
| **Exception:** Function expressions *may* be used *only if* code has to | |
| dynamically rebind `this` (but this is [discouraged](#rebinding-this)), or for | |
| generator functions (which do not have an arrow syntax). | |
| <a id="features-functions-arrow-functions"></a> | |
| <a id="expression-bodies-vs-block-bodies"></a> | |
| <div class="numbered"></div> | |
| <a id="arrow-function-bodies"></a> | |
| #### Arrow function bodies | |
| Use arrow functions with concise bodies (i.e. expressions) or block bodies as | |
| appropriate. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Top level functions use function declarations. | |
| function someFunction() { | |
| // Block bodies are fine: | |
| const receipts = books.map((b: Book) => { | |
| const receipt = payMoney(b.price); | |
| recordTransaction(receipt); | |
| return receipt; | |
| }); | |
| // Concise bodies are fine, too, if the return value is used: | |
| const longThings = | |
| myValues.filter((v) => v.length > 1000).map((v) => String(v)); | |
| function payMoney(amount: number) { | |
| // function declarations are fine, but must not access `this`. | |
| } | |
| // Nested arrow functions may be assigned to a const. | |
| const computeTax = (amount: number) => amount * 0.12; | |
| } | |
| ``` | |
| Only use a concise body if the return value of the function is actually used. | |
| The block body makes sure the return type is `void` then and prevents potential | |
| side effects. | |
| <div class='badcode'></div> | |
| ```ts | |
| // BAD: use a block body if the return value of the function is not used. | |
| myPromise.then((v) => console.log(v)); | |
| // BAD: this typechecks, but the return value still leaks. | |
| let f: () => void; | |
| f = () => 1; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // GOOD: return value is unused, use a block body. | |
| myPromise.then((v) => { | |
| console.log(v); | |
| }); | |
| // GOOD: code may use blocks for readability. | |
| const transformed = [1, 2, 3].map((v) => { | |
| const intermediate = someComplicatedExpr(v); | |
| const more = acrossManyLines(intermediate); | |
| return worthWrapping(more); | |
| }); | |
| // GOOD: explicit `void` ensures no leaked return value | |
| myPromise.then((v) => void console.log(v)); | |
| ``` | |
| Tip: The `void` operator can be used to ensure an arrow function with an | |
| expression body returns `undefined` when the result is unused. | |
| <div class="numbered"></div> | |
| <a id="rebinding-this"></a> | |
| #### Rebinding `this` | |
| Function expressions and function declarations *must not* use `this` unless they | |
| specifically exist to rebind the `this` pointer. Rebinding `this` can in most | |
| cases be avoided by using arrow functions or explicit parameters. | |
| <div class='badcode'></div> | |
| ```ts | |
| function clickHandler() { | |
| // Bad: what's `this` in this context? | |
| this.textContent = 'Hello'; | |
| } | |
| // Bad: the `this` pointer reference is implicitly set to document.body. | |
| document.body.onclick = clickHandler; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Good: explicitly reference the object from an arrow function. | |
| document.body.onclick = () => { document.body.textContent = 'hello'; }; | |
| // Alternatively: take an explicit parameter | |
| const setTextFn = (e: HTMLElement) => { e.textContent = 'hello'; }; | |
| document.body.onclick = setTextFn.bind(null, document.body); | |
| ``` | |
| Prefer arrow functions over other approaches to binding `this`, such as | |
| `f.bind(this)`, `goog.bind(f, this)`, or `const self = this`. | |
| <div class="numbered"></div> | |
| <a id="functions-as-callbacks"></a> | |
| #### Prefer passing arrow functions as callbacks | |
| Callbacks can be invoked with unexpected arguments that can pass a type check | |
| but still result in logical errors. | |
| Avoid passing a named callback to a higher-order function, unless you are sure | |
| of the stability of both functions' call signatures. Beware, in particular, of | |
| less-commonly-used optional parameters. | |
| <div class='badcode'></div> | |
| ```ts | |
| // BAD: Arguments are not explicitly passed, leading to unintended behavior | |
| // when the optional `decimals` argument gets the array indices 0, 1, and 2. | |
| const strs = [1.23, 4.56, 7.89].map(googFormat.numericValueToString); | |
| // > ['1', '4.6', '7.89']; | |
| ``` | |
| Instead, prefer passing an arrow-function that explicitly forwards parameters to | |
| the named callback. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // GOOD: Arguments are explicitly passed to the callback | |
| const strs = [1.23, 4.56, 7.89].map((n) => googFormat.numericValueToString(n)); | |
| // > ['1.23', '4.56', '7.89'] | |
| // GOOD: Function is locally defined and is designed to be used as a callback | |
| function dayFilter(element: string|null|undefined) { | |
| return element != null && element.endsWith('day'); | |
| } | |
| const days = ['tuesday', undefined, 'juice', 'wednesday'].filter(dayFilter); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="arrow-functions-as-properties"></a> | |
| #### Arrow functions as properties | |
| Classes usually *should not* contain properties initialized to arrow functions. | |
| Arrow function properties require the calling function to understand that the | |
| callee's `this` is already bound, which increases confusion about what `this` | |
| is, and call sites and references using such handlers look broken (i.e. require | |
| non-local knowledge to determine that they are correct). Code *should* always | |
| use arrow functions to call instance methods | |
| (`const handler = (x) => { this.listener(x); };`), and *should not* obtain or | |
| pass references to instance methods | |
| (~~`const handler = this.listener; handler(x);`~~). | |
| > Note: in some specific situations, e.g. when binding functions in a template, | |
| > arrow functions as properties are useful and create much more readable code. | |
| > Use judgement with this rule. Also, see the | |
| > [`Event Handlers`](#event-handlers) section below. | |
| <div class='badcode'></div> | |
| ```ts | |
| class DelayHandler { | |
| constructor() { | |
| // Problem: `this` is not preserved in the callback. `this` in the callback | |
| // will not be an instance of DelayHandler. | |
| setTimeout(this.patienceTracker, 5000); | |
| } | |
| private patienceTracker() { | |
| this.waitedPatiently = true; | |
| } | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| // Arrow functions usually should not be properties. | |
| class DelayHandler { | |
| constructor() { | |
| // Bad: this code looks like it forgot to bind `this`. | |
| setTimeout(this.patienceTracker, 5000); | |
| } | |
| private patienceTracker = () => { | |
| this.waitedPatiently = true; | |
| } | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Explicitly manage `this` at call time. | |
| class DelayHandler { | |
| constructor() { | |
| // Use anonymous functions if possible. | |
| setTimeout(() => { | |
| this.patienceTracker(); | |
| }, 5000); | |
| } | |
| private patienceTracker() { | |
| this.waitedPatiently = true; | |
| } | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="event-handlers"></a> | |
| #### Event handlers | |
| Event handlers *may* use arrow functions when there is no need to uninstall the | |
| handler (for example, if the event is emitted by the class itself). If the | |
| handler requires uninstallation, arrow function properties are the right | |
| approach, because they automatically capture `this` and provide a stable | |
| reference to uninstall. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Event handlers may be anonymous functions or arrow function properties. | |
| class Component { | |
| onAttached() { | |
| // The event is emitted by this class, no need to uninstall. | |
| this.addEventListener('click', () => { | |
| this.listener(); | |
| }); | |
| // this.listener is a stable reference, we can uninstall it later. | |
| window.addEventListener('onbeforeunload', this.listener); | |
| } | |
| onDetached() { | |
| // The event is emitted by window. If we don't uninstall, this.listener will | |
| // keep a reference to `this` because it's bound, causing a memory leak. | |
| window.removeEventListener('onbeforeunload', this.listener); | |
| } | |
| // An arrow function stored in a property is bound to `this` automatically. | |
| private listener = () => { | |
| confirm('Do you want to exit the page?'); | |
| } | |
| } | |
| ``` | |
| Do not use `bind` in the expression that installs an event handler, because it | |
| creates a temporary reference that can't be uninstalled. | |
| <div class='badcode'></div> | |
| ```ts | |
| // Binding listeners creates a temporary reference that prevents uninstalling. | |
| class Component { | |
| onAttached() { | |
| // This creates a temporary reference that we won't be able to uninstall | |
| window.addEventListener('onbeforeunload', this.listener.bind(this)); | |
| } | |
| onDetached() { | |
| // This bind creates a different reference, so this line does nothing. | |
| window.removeEventListener('onbeforeunload', this.listener.bind(this)); | |
| } | |
| private listener() { | |
| confirm('Do you want to exit the page?'); | |
| } | |
| } | |
| ``` | |
| <a id="features-functions-default-parameters"></a> | |
| <div class="numbered"></div> | |
| <a id="parameter-initializers"></a> | |
| #### Parameter initializers | |
| Optional function parameters *may* be given a default initializer to use when | |
| the argument is omitted. Initializers *must not* have any observable side | |
| effects. Initializers *should* be kept as simple as possible. | |
| <div class='goodcode'></div> | |
| ```ts | |
| function process(name: string, extraContext: string[] = []) {} | |
| function activate(index = 0) {} | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| // BAD: side effect of incrementing the counter | |
| let globalCounter = 0; | |
| function newId(index = globalCounter++) {} | |
| // BAD: exposes shared mutable state, which can introduce unintended coupling | |
| // between function calls | |
| class Foo { | |
| private readonly defaultPaths: string[]; | |
| frobnicate(paths = defaultPaths) {} | |
| } | |
| ``` | |
| Use default parameters sparingly. Prefer | |
| [destructuring](#features-objects-destructuring) to create readable APIs when | |
| there are more than a small handful of optional parameters that do not have a | |
| natural order. | |
| <a id="features-functions-rest-parameters"></a> | |
| <a id="features-functions-spread-operator"></a> | |
| <div class="numbered"></div> | |
| <a id="rest-and-spread"></a> | |
| #### Prefer rest and spread when appropriate | |
| Use a *rest* parameter instead of accessing `arguments`. Never name a local | |
| variable or parameter `arguments`, which confusingly shadows the built-in name. | |
| <div class='goodcode'></div> | |
| ```ts | |
| function variadic(array: string[], ...numbers: number[]) {} | |
| ``` | |
| Use function spread syntax instead of `Function.prototype.apply`. | |
| <a id="features-functions-generators"></a> | |
| <div class="numbered"></div> | |
| <a id="formatting-functions"></a> | |
| #### Formatting functions | |
| Blank lines at the start or end of the function body are not allowed. | |
| A single blank line *may* be used within function bodies sparingly to create | |
| *logical groupings* of statements. | |
| Generators should attach the `*` to the `function` and `yield` keywords, as in | |
| `function* foo()` and `yield* iter`, rather than ~~`function *foo()`~~ or | |
| ~~`yield *iter`~~. | |
| Parentheses around the left-hand side of a single-argument arrow function are | |
| recommended but not required. | |
| Do not put a space after the `...` in rest or spread syntax. | |
| <div class='goodcode'></div> | |
| ```ts | |
| function myFunction(...elements: number[]) {} | |
| myFunction(...array, ...iterable, ...generator()); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="function-length"></a> | |
| #### Function Length | |
| Write small and focused functions and class methods. | |
| Even though no hard limit is placed on function and method length, if it exceeds | |
| about 40 lines, think about whether it can be broken up without harming the | |
| structure of the program. | |
| This is not an exact science, but here are some examples of signs that your | |
| method might be too complex: | |
| * It has several levels of nesting. | |
| * It consists of several separate blocks of code, that each require a comment | |
| to explain what it does. | |
| * It has to handle different types of exceptions in different places. | |
| * It can't all fit on your screen at once. | |
| If working with such a function proves to be difficult, you find that errors are | |
| hard to debug, or you want to use a piece of it in several different contexts, | |
| consider breaking up the function into smaller and more manageable pieces. Note | |
| that there is nothing wrong with a private helper method or class that is used | |
| only once; these can be a useful tool for making code more readable. | |
| <div class="numbered"></div> | |
| <a id="features-this"></a> | |
| ### this | |
| Only use `this` in class constructors and methods, functions that have an | |
| explicit `this` type declared (e.g. `function func(this: ThisType, ...)`), or in | |
| arrow functions defined in a scope where `this` may be used. | |
| Never use `this` to refer to the global object, the context of an `eval`, the | |
| target of an event, or unnecessarily `call()`ed or `apply()`ed functions. | |
| <div class='badcode'></div> | |
| ```ts | |
| this.alert('Hello'); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="primitive-literals"></a> | |
| ### Primitive literals | |
| <a id="features-string-literals"></a> | |
| <div class="numbered"></div> | |
| <a id="string-literals"></a> | |
| #### String literals | |
| <a id="features-strings-use-single-quotes"></a> | |
| <div class="numbered"></div> | |
| <a id="use-single-quotes"></a> | |
| ##### Use single quotes | |
| Ordinary string literals are delimited with single quotes (`'`), rather than | |
| double quotes (`"`). | |
| Exception: if a string contains a single quote character, it may be delimited | |
| with double quotes to avoid having to escape the quote. | |
| <a id="syntax-no-line-continuations"></a> | |
| <a id="features-strings-no-line-continuations"></a> | |
| <div class="numbered"></div> | |
| <a id="no-line-continuations"></a> | |
| ##### No line continuations | |
| Do not use *line continuations* (that is, ending a line inside a string literal | |
| with a backslash) in either ordinary or template string literals. Even though | |
| ES5 allows this, it can lead to tricky errors if any trailing whitespace comes | |
| after the slash, and is less obvious to readers. | |
| Disallowed: | |
| <div class='badcode'></div> | |
| ```ts | |
| const LONG_STRING = 'This is a very very very very very very very long string. \ | |
| It inadvertently contains long stretches of spaces due to how the \ | |
| continued lines are indented.'; | |
| ``` | |
| Instead, write | |
| <div class='goodcode'></div> | |
| ```ts | |
| const LONG_STRING = 'This is a very very very very very very long string. ' + | |
| 'It does not contain long stretches of spaces because it uses ' + | |
| 'concatenated strings.'; | |
| const SINGLE_STRING = | |
| 'http://it.is.also/acceptable_to_use_a_single_long_string_when_breaking_would_hinder_search_discoverability'; | |
| ``` | |
| <a id="features-strings-template-strings"></a> | |
| <div class="numbered"></div> | |
| <a id="template-literals"></a> | |
| ##### Template literals | |
| Use template literals (delimited with `` ` ``) over complex string | |
| concatenation, particularly if multiple string literals are involved. Template | |
| literals may span multiple lines. | |
| If a template literal spans multiple lines, it does not need to follow the | |
| indentation of the enclosing block, though it may if the added whitespace does | |
| not matter. | |
| Example: | |
| <div class='goodcode'></div> | |
| ```ts | |
| function arithmetic(a: number, b: number) { | |
| return `Here is a table of arithmetic operations: | |
| ${a} + ${b} = ${a + b} | |
| ${a} - ${b} = ${a - b} | |
| ${a} * ${b} = ${a * b} | |
| ${a} / ${b} = ${a / b}`; | |
| } | |
| ``` | |
| <a id="features-number-literals"></a> | |
| <div class="numbered"></div> | |
| <a id="number-literals"></a> | |
| #### Number literals | |
| Numbers may be specified in decimal, hex, octal, or binary. Use exactly `0x`, | |
| `0o`, and `0b` prefixes, with lowercase letters, for hex, octal, and binary, | |
| respectively. Never include a leading zero unless it is immediately followed by | |
| `x`, `o`, or `b`. | |
| <div class="numbered"></div> | |
| <a id="type-coercion"></a> | |
| #### Type coercion | |
| TypeScript code *may* use the `String()` and `Boolean()` (note: no `new`!) | |
| functions, string template literals, or `!!` to coerce types. | |
| <div class='goodcode'></div> | |
| ```ts | |
| const bool = Boolean(0); | |
| const str = String(aNumber); | |
| const bool2 = !!str; | |
| const str2 = `result: ${bool2}`; | |
| ``` | |
| Values of enum types (including unions of enum types and other types) *must not* | |
| be converted to booleans with `Boolean()` or `!!`, and must instead be compared | |
| explicitly with comparison operators. | |
| <div class='badcode'></div> | |
| ```ts | |
| enum SupportLevel { | |
| NONE, | |
| BASIC, | |
| ADVANCED, | |
| } | |
| const level: SupportLevel = ...; | |
| let enabled = Boolean(level); | |
| const maybeLevel: SupportLevel|undefined = ...; | |
| enabled = !!maybeLevel; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| enum SupportLevel { | |
| NONE, | |
| BASIC, | |
| ADVANCED, | |
| } | |
| const level: SupportLevel = ...; | |
| let enabled = level !== SupportLevel.NONE; | |
| const maybeLevel: SupportLevel|undefined = ...; | |
| enabled = maybeLevel !== undefined && maybeLevel !== SupportLevel.NONE; | |
| ``` | |
| Why? | |
| For most purposes, it doesn't matter what number or string value an enum name is | |
| mapped to at runtime, because values of enum types are referred to by name in | |
| source code. Consequently, engineers are accustomed to not thinking about this, | |
| and so situations where it *does* matter are undesirable because they will be | |
| surprising. Such is the case with conversion of enums to booleans; in | |
| particular, by default, the first declared enum value is falsy (because it is 0) | |
| while the others are truthy, which is likely to be unexpected. Readers of code | |
| that uses an enum value may not even know whether it's the first declared value | |
| or not. | |
| Using string concatenation to cast to string is discouraged, as we check that | |
| operands to the plus operator are of matching types. | |
| <div class="numbered"></div> | |
| <a id="coercing-to-numbers"></a> | |
| ##### Coercing to numbers | |
| Number parsing can fail in a wide variety of ways, with many surprising corner | |
| cases, and the different methods to parse numbers each have different and | |
| sometimes inconsistent behavior (e.g. whitespace, empty strings, scientific | |
| notation, overflow to infinity, radix prefixes, etc). Further, parsing at the | |
| wrong layer can often be a code smell. Code *must* check the output of any | |
| numeric coercion and explicitly handle any possible non-throwing failure cases | |
| (e.g. handling any `NaN` results). | |
| Code *must not* use unary plus (e.g. `+str`) or `parseFloat` to coerce strings | |
| to numbers. The former is too easy to miss in a code review, and the latter | |
| silently ignores trailing garbage in the input string. In both cases, prefer | |
| `Number` instead. | |
| Code *must not* use `parseInt` unless a non-decimal radix is required. In this | |
| case, the input string *must* be checked for validity (i.e. all characters are | |
| valid digits) before parsing to ensure trailing garbage is not silently ignored. | |
| The output *must* also be checked against `NaN`. | |
| <div class='badcode'></div> | |
| ```ts | |
| const x = +y; | |
| const x1 = parseFloat(y1); | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| const x = Number(y); | |
| if (!isFinite(x)) throw new Error(...); | |
| ``` | |
| <a id="type-coercion-implicit"></a> | |
| <div class="numbered"></div> | |
| <a id="implicit-coercion"></a> | |
| ##### Implicit coercion | |
| Do not use explicit boolean coercions in conditional clauses that have implicit | |
| boolean coercion (specifically, the conditions in `if`, `for`, and `while` | |
| statements). | |
| <div class='badcode'></div> | |
| ```ts | |
| const foo: MyInterface|null = ...; | |
| if (!!foo) {...} | |
| while (!!foo) {...} | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| const foo: MyInterface|null = ...; | |
| if (foo) {...} | |
| while (foo) {...} | |
| ``` | |
| [As with explicit conversions](#type-coercion), values of enum types (including | |
| unions of enum types and other types) *must not* be implicitly coerced to | |
| booleans, and must instead be compared explicitly with comparison operators. | |
| <div class='badcode'></div> | |
| ```ts | |
| enum SupportLevel { | |
| NONE, | |
| BASIC, | |
| ADVANCED, | |
| } | |
| const level: SupportLevel = ...; | |
| if (level) {...} | |
| const maybeLevel: SupportLevel|undefined = ...; | |
| if (maybeLevel) {...} | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| enum SupportLevel { | |
| NONE, | |
| BASIC, | |
| ADVANCED, | |
| } | |
| const level: SupportLevel = ...; | |
| if (level !== SupportLevel.NONE) {...} | |
| const maybeLevel: SupportLevel|undefined = ...; | |
| if (maybeLevel !== undefined && maybeLevel !== SupportLevel.NONE) {...} | |
| ``` | |
| Other types of values may be either implicitly coerced to booleans or compared | |
| explicitly with comparison operators: | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Explicitly comparing > 0 is OK: | |
| if (arr.length > 0) {...} | |
| // so is relying on boolean coercion: | |
| if (arr.length) {...} | |
| ``` | |
| <a id="features-control-structures"></a> | |
| <div class="numbered"></div> | |
| <a id="control-structures"></a> | |
| ### Control structures | |
| <a id="formatting-braces"></a> | |
| <a id="formatting-braces-all"></a> | |
| <div class="numbered"></div> | |
| <a id="control-flow-statements-blocks"></a> | |
| #### Control flow statements and blocks | |
| Control flow statements (`if`, `else`, `for`, `do`, `while`, etc) always use | |
| braced blocks for the containing code, even if the body contains only a single | |
| statement. The first statement of a non-empty block must begin on its own line. | |
| <div class='goodcode'></div> | |
| ```ts | |
| for (let i = 0; i < x; i++) { | |
| doSomethingWith(i); | |
| } | |
| if (x) { | |
| doSomethingWithALongMethodNameThatForcesANewLine(x); | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| if (x) | |
| doSomethingWithALongMethodNameThatForcesANewLine(x); | |
| for (let i = 0; i < x; i++) doSomethingWith(i); | |
| ``` | |
| **Exception:** `if` statements fitting on one line *may* elide the block. | |
| <div class='goodcode'></div> | |
| ```ts | |
| if (x) x.doFoo(); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="assignment-in-control-statements"></a> | |
| ##### Assignment in control statements | |
| Prefer to avoid assignment of variables inside control statements. Assignment | |
| can be easily mistaken for equality checks inside control statements. | |
| <div class='badcode'></div> | |
| ```ts | |
| if (x = someFunction()) { | |
| // Assignment easily mistaken with equality check | |
| // ... | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| x = someFunction(); | |
| if (x) { | |
| // ... | |
| } | |
| ``` | |
| In cases where assignment inside the control statement is preferred, enclose the | |
| assignment in additional parenthesis to indicate it is intentional. | |
| ```ts | |
| while ((x = someFunction())) { | |
| // Double parenthesis shows assignment is intentional | |
| // ... | |
| } | |
| ``` | |
| <a id="features-for-loops"></a> | |
| <div class="numbered"></div> | |
| <a id="iterating-containers"></a> | |
| ##### Iterating containers | |
| Prefer `for (... of someArr)` to iterate over arrays. `Array.prototype.forEach` | |
| and vanilla `for` loops are also allowed: | |
| <div class='goodcode'></div> | |
| ```ts | |
| for (const x of someArr) { | |
| // x is a value of someArr. | |
| } | |
| for (let i = 0; i < someArr.length; i++) { | |
| // Explicitly count if the index is needed, otherwise use the for/of form. | |
| const x = someArr[i]; | |
| // ... | |
| } | |
| for (const [i, x] of someArr.entries()) { | |
| // Alternative version of the above. | |
| } | |
| ``` | |
| `for`-`in` loops may only be used on dict-style objects (see | |
| [below](#optimization-compatibility-for-property-access) for more info). Do not | |
| use `for (... in ...)` to iterate over arrays as it will counterintuitively give | |
| the array's indices (as strings!), not values: | |
| <div class='badcode'></div> | |
| ```ts | |
| for (const x in someArray) { | |
| // x is the index! | |
| } | |
| ``` | |
| `Object.prototype.hasOwnProperty` should be used in `for`-`in` loops to exclude | |
| unwanted prototype properties. Prefer `for`-`of` with `Object.keys`, | |
| `Object.values`, or `Object.entries` over `for`-`in` when possible. | |
| <div class='goodcode'></div> | |
| ```ts | |
| for (const key in obj) { | |
| if (!obj.hasOwnProperty(key)) continue; | |
| doWork(key, obj[key]); | |
| } | |
| for (const key of Object.keys(obj)) { | |
| doWork(key, obj[key]); | |
| } | |
| for (const value of Object.values(obj)) { | |
| doWorkValOnly(value); | |
| } | |
| for (const [key, value] of Object.entries(obj)) { | |
| doWork(key, value); | |
| } | |
| ``` | |
| <a id="formatting-grouping-parentheses"></a> | |
| <div class="numbered"></div> | |
| <a id="grouping-parentheses"></a> | |
| #### Grouping parentheses | |
| Optional grouping parentheses are omitted only when the author and reviewer | |
| agree that there is no reasonable chance that the code will be misinterpreted | |
| without them, nor would they have made the code easier to read. It is *not* | |
| reasonable to assume that every reader has the entire operator precedence table | |
| memorized. | |
| Do not use unnecessary parentheses around the entire expression following | |
| `delete`, `typeof`, `void`, `return`, `throw`, `case`, `in`, `of`, or `yield`. | |
| <a id="exceptions"></a> | |
| <a id="features-exceptions"></a> | |
| <div class="numbered"></div> | |
| <a id="exception-handling"></a> | |
| #### Exception handling | |
| Exceptions are an important part of the language and should be used whenever | |
| exceptional cases occur. | |
| Custom exceptions provide a great way to convey additional error information | |
| from functions. They should be defined and used wherever the native `Error` type | |
| is insufficient. | |
| Prefer throwing exceptions over ad-hoc error-handling approaches (such as | |
| passing an error container reference type, or returning an object with an error | |
| property). | |
| <div class="numbered"></div> | |
| <a id="instantiate-errors-using-new"></a> | |
| ##### Instantiate errors using `new` | |
| Always use `new Error()` when instantiating exceptions, instead of just calling | |
| `Error()`. Both forms create a new `Error` instance, but using `new` is more | |
| consistent with how other objects are instantiated. | |
| <div class='goodcode'></div> | |
| ```ts | |
| throw new Error('Foo is not a valid bar.'); | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| throw Error('Foo is not a valid bar.'); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="only-throw-errors"></a> | |
| ##### Only throw errors | |
| Although JavaScript allows throwing arbitrary values, stack traces are only | |
| populated if the thrown value is an `Error`. **Do not** throw primitives | |
| (including strings, numbers, null or undefined) or objects that are not | |
| instances of `Error` or a subclass. This restriction also extends to all APIs | |
| that may throw their arguments, including `Promise.reject` or `AbortSignal`'s | |
| various `abort` methods. | |
| <div class='badcode'></div> | |
| ```ts | |
| // bad: does not get a stack trace. | |
| throw 'oh noes!'; | |
| // For promises | |
| new Promise((resolve, reject) => void reject('oh noes!')); | |
| Promise.reject(); | |
| Promise.reject('oh noes!'); | |
| // For abort signals | |
| new AbortController().abort('my custom abort error'); | |
| AbortSignal.abort('my other custom abort error'); | |
| ``` | |
| Instead, only throw (subclasses of) `Error`: | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Throw only Errors | |
| throw new Error('oh noes!'); | |
| // ... or subtypes of Error. | |
| class MyError extends Error {} | |
| throw new MyError('my oh noes!'); | |
| // For promises | |
| new Promise((resolve) => resolve()); // No reject is OK. | |
| new Promise((resolve, reject) => void reject(new Error('oh noes!'))); | |
| Promise.reject(new Error('oh noes!')); | |
| // For abort signals | |
| new AbortController().abort(); // No reason is OK. | |
| AbortSignal.abort(); | |
| new AbortController().abort(new Error('my custom abort error')); | |
| AbortSignal.abort(new Error('my other custom abort error')); | |
| ``` | |
| Note: Calling `AbortController#abort` or `AbortSignal.abort` with no arguments | |
| is valid because a new "AbortError" `DOMException` will be created by default | |
| and assigned as the `AbortSignal#reason` (see | |
| [MDN](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort#reason)). | |
| <div class="numbered"></div> | |
| <a id="catching-and-rethrowing"></a> | |
| ##### Catching and rethrowing | |
| When catching errors, code *should* assume that all thrown errors are instances | |
| of `Error`. | |
| <div class='goodcode'></div> | |
| ```ts | |
| function assertIsError(e: unknown): asserts e is Error { | |
| if (!(e instanceof Error)) throw new Error("e is not an Error"); | |
| } | |
| try { | |
| doSomething(); | |
| } catch (e: unknown) { | |
| // All thrown errors must be Error subtypes. Do not handle | |
| // other possible values unless you know they are thrown. | |
| assertIsError(e); | |
| displayError(e.message); | |
| // or rethrow: | |
| throw e; | |
| } | |
| ``` | |
| Exception handlers *must not* defensively handle non-`Error` types unless the | |
| called API is conclusively known to throw non-`Error`s in violation of the above | |
| rule. In that case, a comment should be included to specifically identify where | |
| the non-`Error`s originate. | |
| <div class='goodcode'></div> | |
| ```ts | |
| try { | |
| badApiThrowingStrings(); | |
| } catch (e: unknown) { | |
| // Note: bad API throws strings instead of errors. | |
| if (typeof e === 'string') { ... } | |
| } | |
| ``` | |
| Why? | |
| Avoid | |
| [overly defensive programming](https://en.wikipedia.org/wiki/Defensive_programming#Offensive_programming). | |
| Repeating the same defenses against a problem that will not exist in most code | |
| leads to boiler-plate code that is not useful. | |
| <a id="features-empty-catch-blocks"></a> | |
| <div class="numbered"></div> | |
| <a id="empty-catch-blocks"></a> | |
| ##### Empty catch blocks | |
| It is very rarely correct to do nothing in response to a caught exception. When | |
| it truly is appropriate to take no action whatsoever in a catch block, the | |
| reason this is justified is explained in a comment. | |
| <div class='goodcode'></div> | |
| ```ts | |
| try { | |
| return handleNumericResponse(response); | |
| } catch (e: unknown) { | |
| // Response is not numeric. Continue to handle as text. | |
| } | |
| return handleTextResponse(response); | |
| ``` | |
| Disallowed: | |
| <div class='badcode'></div> | |
| ```ts | |
| try { | |
| shouldFail(); | |
| fail('expected an error'); | |
| } catch (expected: unknown) { | |
| } | |
| ``` | |
| Tip: Unlike in some other languages, patterns like the above simply don’t work | |
| since this will catch the error thrown by `fail`. Use `assertThrows()` instead. | |
| <a id="features-switch-statements"></a> | |
| <a id="features-switch-default-case"></a> | |
| <div class="numbered"></div> | |
| <a id="error-cause"></a> | |
| ##### ErrorOptions cause must be an Error object | |
| When passing an argument for the ErrorOptions parameter, the `cause` property | |
| must be initialized with a subtype of error. This effectively creates a chain of | |
| error objects with useful stack traces. | |
| <div class='goodcode'></div> | |
| ```ts | |
| try { | |
| ... | |
| } catch (e: unknown) { | |
| if (e instanceof Error) { | |
| throw new Error('Something went wrong', {cause: e}); | |
| } | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| const status = doSomething(); | |
| if (status !== success) { | |
| throw new Error('doSomething failed', {cause: status}); | |
| } | |
| ``` | |
| If the `cause` initializer refers to the catch clause variable of type unknown, | |
| it's ok to omit a type check, since our codebase assumes you cannot throw | |
| anything other than an `Error` object. | |
| <div class='goodcode'></div> | |
| ```ts | |
| try { | |
| ... | |
| } catch (e: unknown) { | |
| // No need to check the type of e. | |
| throw new Error('Something went wrong', {cause: e}); | |
| } | |
| ``` | |
| In TypeScript, type `Error` happens to be assignable to `ErrorOptions`. Thus it | |
| is possible to pass an error object accidentally as the ErrorOptions parameter, | |
| which is very likely a bug in the code. | |
| <div class='badcode'></div> | |
| ```ts | |
| try { | |
| ... | |
| } catch (e: unknown) { | |
| if (e instanceof Error) { | |
| throw new Error('Something went wrong', e); | |
| } | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="switch-statements"></a> | |
| #### Switch statements | |
| All `switch` statements *must* contain a `default` statement group, even if it | |
| contains no code. The `default` statement group must be last. | |
| <div class='goodcode'></div> | |
| ```ts | |
| switch (x) { | |
| case Y: | |
| doSomethingElse(); | |
| break; | |
| default: | |
| // nothing to do. | |
| } | |
| ``` | |
| Within a switch block, each statement group either terminates abruptly with a | |
| `break`, a `return` statement, or by throwing an exception. Non-empty statement | |
| groups (`case ...`) *must not* fall through (enforced by the compiler): | |
| <div class='badcode'></div> | |
| ```ts | |
| switch (x) { | |
| case X: | |
| doSomething(); | |
| // fall through - not allowed! | |
| case Y: | |
| // ... | |
| } | |
| ``` | |
| Empty statement groups are allowed to fall through: | |
| <div class='goodcode'></div> | |
| ```ts | |
| switch (x) { | |
| case X: | |
| case Y: | |
| doSomething(); | |
| break; | |
| default: // nothing to do. | |
| } | |
| ``` | |
| <a id="features-equality-checks"></a> | |
| <a id="features-equality-checks-exceptions"></a> | |
| <div class="numbered"></div> | |
| <a id="equality-checks"></a> | |
| #### Equality checks | |
| Always use triple equals (`===`) and not equals (`!==`). The double equality | |
| operators cause error prone type coercions that are hard to understand and | |
| slower to implement for JavaScript Virtual Machines. See also the | |
| [JavaScript equality table](https://dorey.github.io/JavaScript-Equality-Table/). | |
| <div class='badcode'></div> | |
| ```ts | |
| if (foo == 'bar' || baz != bam) { | |
| // Hard to understand behaviour due to type coercion. | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| if (foo === 'bar' || baz !== bam) { | |
| // All good here. | |
| } | |
| ``` | |
| **Exception:** Comparisons to the literal `null` value *may* use the `==` and | |
| `!=` operators to cover both `null` and `undefined` values. | |
| <div class='goodcode'></div> | |
| ```ts | |
| if (foo == null) { | |
| // Will trigger when foo is null or undefined. | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="type-and-non-nullability-assertions"></a> | |
| #### Type and non-nullability assertions | |
| Type assertions (`x as SomeType`) and non-nullability assertions (`y!`) are | |
| unsafe. Both only silence the TypeScript compiler, but do not insert any runtime | |
| checks to match these assertions, so they can cause your program to crash at | |
| runtime. | |
| Because of this, you *should not* use type and non-nullability assertions | |
| without an obvious or explicit reason for doing so. | |
| Instead of the following: | |
| <div class='badcode'></div> | |
| ```ts | |
| (x as Foo).foo(); | |
| y!.bar(); | |
| ``` | |
| When you want to assert a type or non-nullability the best answer is to | |
| explicitly write a runtime check that performs that check. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // assuming Foo is a class. | |
| if (x instanceof Foo) { | |
| x.foo(); | |
| } | |
| if (y) { | |
| y.bar(); | |
| } | |
| ``` | |
| Sometimes due to some local property of your code you can be sure that the | |
| assertion form is safe. In those situations, you *should* add clarification to | |
| explain why you are ok with the unsafe behavior: | |
| <div class='goodcode'></div> | |
| ```ts | |
| // x is a Foo, because ... | |
| (x as Foo).foo(); | |
| // y cannot be null, because ... | |
| y!.bar(); | |
| ``` | |
| If the reasoning behind a type or non-nullability assertion is obvious, the | |
| comments *may* not be necessary. For example, generated proto code is always | |
| nullable, but perhaps it is well-known in the context of the code that certain | |
| fields are always provided by the backend. Use your judgement. | |
| <div class="numbered"></div> | |
| <a id="type-assertions-syntax"></a> | |
| ##### Type assertion syntax | |
| Type assertions *must* use the `as` syntax (as opposed to the angle brackets | |
| syntax). This enforces parentheses around the assertion when accessing a member. | |
| <div class='badcode'></div> | |
| ```ts | |
| const x = (<Foo>z).length; | |
| const y = <Foo>z.length; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // z must be Foo because ... | |
| const x = (z as Foo).length; | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="double-assertions"></a> | |
| ##### Double assertions | |
| From the | |
| [TypeScript handbook](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions), | |
| TypeScript only allows type assertions which convert to a *more specific* or | |
| *less specific* version of a type. Adding a type assertion (`x as Foo`) which | |
| does not meet this criteria will give the error: "Conversion of type 'X' to type | |
| 'Y' may be a mistake because neither type sufficiently overlaps with the other." | |
| If you are sure an assertion is safe, you can perform a *double assertion*. This | |
| involves casting through `unknown` since it is less specific than all types. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // x is a Foo here, because... | |
| (x as unknown as Foo).fooMethod(); | |
| ``` | |
| Use `unknown` (instead of `any` or `{}`) as the intermediate type. | |
| <div class="numbered"></div> | |
| <a id="type-assertions-and-object-literals"></a> | |
| ##### Type assertions and object literals | |
| Use type annotations (`: Foo`) instead of type assertions (`as Foo`) to specify | |
| the type of an object literal. This allows detecting refactoring bugs when the | |
| fields of an interface change over time. | |
| <div class='badcode'></div> | |
| ```ts | |
| interface Foo { | |
| bar: number; | |
| baz?: string; // was "bam", but later renamed to "baz". | |
| } | |
| const foo = { | |
| bar: 123, | |
| bam: 'abc', // no error! | |
| } as Foo; | |
| function func() { | |
| return { | |
| bar: 123, | |
| bam: 'abc', // no error! | |
| } as Foo; | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| interface Foo { | |
| bar: number; | |
| baz?: string; | |
| } | |
| const foo: Foo = { | |
| bar: 123, | |
| bam: 'abc', // complains about "bam" not being defined on Foo. | |
| }; | |
| function func(): Foo { | |
| return { | |
| bar: 123, | |
| bam: 'abc', // complains about "bam" not being defined on Foo. | |
| }; | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="keep-try-blocks-focused"></a> | |
| #### Keep try blocks focused | |
| Limit the amount of code inside a try block, if this can be done without hurting | |
| readability. | |
| <div class='badcode'></div> | |
| ```ts | |
| try { | |
| const result = methodThatMayThrow(); | |
| use(result); | |
| } catch (error: unknown) { | |
| // ... | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| let result; | |
| try { | |
| result = methodThatMayThrow(); | |
| } catch (error: unknown) { | |
| // ... | |
| } | |
| use(result); | |
| ``` | |
| Moving the non-throwable lines out of the try/catch block helps the reader learn | |
| which method throws exceptions. Some inline calls that do not throw exceptions | |
| could stay inside because they might not be worth the extra complication of a | |
| temporary variable. | |
| **Exception:** There may be performance issues if try blocks are inside a loop. | |
| Widening try blocks to cover a whole loop is ok. | |
| <div class="numbered"></div> | |
| <a id="decorators"></a> | |
| ### Decorators | |
| Decorators are syntax with an `@` prefix, like `@MyDecorator`. | |
| Do not define new decorators. Only use the decorators defined by frameworks: | |
| - Angular (e.g. `@Component`, `@NgModule`, etc.) | |
| - Polymer (e.g. `@property`) | |
| Why? | |
| We generally want to avoid decorators, because they were an experimental feature | |
| that have since diverged from the TC39 proposal and have known bugs that won't | |
| be fixed. | |
| When using decorators, the decorator *must* immediately precede the symbol it | |
| decorates, with no empty lines between: | |
| ```ts | |
| /** JSDoc comments go before decorators */ | |
| @Component({...}) // Note: no empty line after the decorator. | |
| class MyComp { | |
| @Input() myField: string; // Decorators on fields may be on the same line... | |
| @Input() | |
| myOtherField: string; // ... or wrap. | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="disallowed-features"></a> | |
| ### Disallowed features | |
| <a id="disallowed-features-wrapper-objects"></a> | |
| <div class="numbered"></div> | |
| <a id="primitive-types-wrapper-classes"></a> | |
| #### Wrapper objects for primitive types | |
| TypeScript code *must not* instantiate the wrapper classes for the primitive | |
| types `String`, `Boolean`, and `Number`. Wrapper classes have surprising | |
| behavior, such as `new Boolean(false)` evaluating to `true`. | |
| <div class='badcode'></div> | |
| ```ts | |
| const s = new String('hello'); | |
| const b = new Boolean(false); | |
| const n = new Number(5); | |
| ``` | |
| The wrappers may be called as functions for coercing (which is preferred over | |
| using `+` or concatenating the empty string) or creating symbols. See | |
| [type coercion](#type-coercion) for more information. | |
| <a id="formatting-semicolons-are-required"></a> | |
| <a id="disallowed-features-automatic-semicolon-insertion"></a> | |
| <div class="numbered"></div> | |
| <a id="automatic-semicolon-insertion"></a> | |
| #### Automatic Semicolon Insertion | |
| Do not rely on Automatic Semicolon Insertion (ASI). Explicitly end all | |
| statements using a semicolon. This prevents bugs due to incorrect semicolon | |
| insertions. | |
| <div class="numbered"></div> | |
| <a id="enums"></a> | |
| #### Const enums | |
| Code *must not* use `const enum`; use plain `enum` instead. | |
| Why? | |
| TypeScript enums already cannot be mutated; `const enum` is a separate language | |
| feature related to optimization that makes the enum invisible to JavaScript | |
| users of the module. | |
| <div class="numbered"></div> | |
| <a id="debugger-statements"></a> | |
| #### Debugger statements | |
| Debugger statements *must not* be included in production code. | |
| <div class='badcode'></div> | |
| ```ts | |
| function debugMe() { | |
| debugger; | |
| } | |
| ``` | |
| <a id="disallowed-features-with"></a> | |
| <div class="numbered"></div> | |
| <a id="diallowed-features-with"></a> | |
| #### `with` | |
| Do not use the `with` keyword. It makes your code harder to understand and | |
| [has been banned in strict mode since ES5](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with). | |
| <a id="disallowed-features-dynamic-code-evaluation"></a> | |
| <div class="numbered"></div> | |
| <a id="dynamic-code-evaluation"></a> | |
| #### Dynamic code evaluation | |
| Do not use `eval` or the `Function(...string)` constructor (except for code | |
| loaders). These features are potentially dangerous and simply do not work in | |
| environments using strict | |
| [Content Security Policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). | |
| <a id="disallowed-features-non-standard-features"></a> | |
| <div class="numbered"></div> | |
| <a id="non-standard-features"></a> | |
| #### Non-standard features | |
| Do not use non-standard ECMAScript or Web Platform features. | |
| This includes: | |
| - Old features that have been marked deprecated or removed entirely from | |
| ECMAScript / the Web Platform (see | |
| [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Deprecated_and_obsolete_features)) | |
| - New ECMAScript features that are not yet standardized | |
| - Avoid using features that are in current TC39 working draft or currently | |
| in the [proposal process](https://tc39.es/process-document/) | |
| - Use only ECMAScript features defined in the current ECMA-262 | |
| specification | |
| - Proposed but not-yet-complete web standards: | |
| - WHATWG proposals that have not completed the | |
| [proposal process](https://whatwg.org/faq#adding-new-features). | |
| - Non-standard language “extensions” (such as those provided by some external | |
| transpilers) | |
| Projects targeting specific JavaScript runtimes, such as latest-Chrome-only, | |
| Chrome extensions, Node.JS, Electron, can obviously use those APIs. Use caution | |
| when considering an API surface that is proprietary and only implemented in some | |
| browsers; consider whether there is a common library that can abstract this API | |
| surface away for you. | |
| <a id="disallowed-features-modifying-builtin-objects"></a> | |
| <div class="numbered"></div> | |
| <a id="modifying-builtin-objects"></a> | |
| #### Modifying built-in objects | |
| Never modify built-in types, either by adding methods to their constructors or | |
| to their prototypes. Avoid depending on libraries that do this. | |
| Do not add symbols to the global object unless absolutely necessary (e.g. | |
| required by a third-party API). | |
| <a id="syntax"></a> | |
| <a id="naming-rules-common-to-all-identifiers"></a> | |
| <div class="numbered"></div> | |
| <a id="naming"></a> | |
| ## Naming | |
| <div class="numbered"></div> | |
| <a id="identifiers"></a> | |
| ### Identifiers | |
| Identifiers *must* use only ASCII letters, digits, underscores (for constants | |
| and structured test method names), and (rarely) the '$' sign. | |
| <div class="numbered"></div> | |
| <a id="naming-style"></a> | |
| #### Naming style | |
| TypeScript expresses information in types, so names *should not* be decorated | |
| with information that is included in the type. (See also | |
| [Testing Blog](https://testing.googleblog.com/2017/10/code-health-identifiernamingpostforworl.html) | |
| for more about what not to include.) | |
| Some concrete examples of this rule: | |
| * Do not use trailing or leading underscores for private properties or | |
| methods. | |
| * Do not use the `opt_` prefix for optional parameters. | |
| * For accessors, see [accessor rules](#classes-getters-and-setters) below. | |
| * Do not mark interfaces specially (~~`IMyInterface`~~ or | |
| ~~`MyFooInterface`~~) unless it's idiomatic in its environment. When | |
| introducing an interface for a class, give it a name that expresses why the | |
| interface exists in the first place (e.g. `class TodoItem` and | |
| `interface TodoItemStorage` if the interface expresses the format used for | |
| storage/serialization in JSON). | |
| * Suffixing `Observable`s with `$` is a common external convention and can | |
| help resolve confusion regarding observable values vs concrete values. | |
| Judgement on whether this is a useful convention is left up to individual | |
| teams, but *should* be consistent within projects. | |
| <a id="identifiers-abbreviations"></a> | |
| <div class="numbered"></div> | |
| <a id="descriptive-names"></a> | |
| #### Descriptive names | |
| Names *must* be descriptive and clear to a new reader. Do not use abbreviations | |
| that are ambiguous or unfamiliar to readers outside your project, and do not | |
| abbreviate by deleting letters within a word. | |
| * **Exception:** Variables that are in scope for 10 lines or fewer, including | |
| arguments that are *not* part of an exported API, *may* use short (e.g. | |
| single letter) variable names. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Good identifiers: | |
| errorCount // No abbreviation. | |
| dnsConnectionIndex // Most people know what "DNS" stands for. | |
| referrerUrl // Ditto for "URL". | |
| customerId // "Id" is both ubiquitous and unlikely to be misunderstood. | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| // Disallowed identifiers: | |
| n // Meaningless. | |
| nErr // Ambiguous abbreviation. | |
| nCompConns // Ambiguous abbreviation. | |
| wgcConnections // Only your group knows what this stands for. | |
| pcReader // Lots of things can be abbreviated "pc". | |
| cstmrId // Deletes internal letters. | |
| kSecondsPerDay // Do not use Hungarian notation. | |
| customerID // Incorrect camelcase of "ID". | |
| ``` | |
| <a id="naming-camel-case-defined"></a> | |
| <div class="numbered"></div> | |
| <a id="camel-case"></a> | |
| #### Camel case | |
| Treat abbreviations like acronyms in names as whole words, i.e. use | |
| `loadHttpUrl`, not ~~`loadHTTPURL`~~, unless required by a platform name (e.g. | |
| `XMLHttpRequest`). | |
| <div class="numbered"></div> | |
| <a id="identifiers-dollar-sign"></a> | |
| #### Dollar sign | |
| Identifiers *should not* generally use `$`, except when required by naming | |
| conventions for third party frameworks. [See above](#naming-style) for more on | |
| using `$` with `Observable` values. | |
| <a id="naming-class-names"></a> | |
| <a id="naming-method-names"></a> | |
| <a id="naming-enum-names"></a> | |
| <a id="naming-constant-names"></a> | |
| <a id="naming-local-variable-names"></a> | |
| <a id="naming-non-constant-field-names"></a> | |
| <a id="naming-parameter-names"></a> | |
| <div class="numbered"></div> | |
| <a id="naming-rules-by-identifier-type"></a> | |
| ### Rules by identifier type | |
| Most identifier names should follow the casing in the table below, based on the | |
| identifier's type. | |
| <!-- mdformat off --> | |
| | Style | Category | | |
| | ---------------- | -------- | | |
| | `UpperCamelCase` | class / interface / type / enum / decorator / type parameters / component functions in TSX / JSXElement type parameter | | |
| | `lowerCamelCase` | variable / parameter / function / method / property / module alias | | |
| | `CONSTANT_CASE` | global constant values, including enum values. See [Constants](#identifiers-constants) below. | | |
| | `#ident` | private identifiers are never used. | | |
| <!-- mdformat on --> | |
| <a id="naming-template-parameter-names"></a> | |
| <div class="numbered"></div> | |
| <a id="identifiers-type-parameters"></a> | |
| #### Type parameters | |
| Type parameters, like in `Array<T>`, *may* use a single upper case character | |
| (`T`) or `UpperCamelCase`. | |
| <div class="numbered"></div> | |
| <a id="identifiers-test-names"></a> | |
| #### Test names | |
| Test method names inxUnit-style test frameworks *may* be structured with `_` | |
| separators, e.g. `testX_whenY_doesZ()`. | |
| <div class="numbered"></div> | |
| <a id="identifiers-underscore-prefix-suffix"></a> | |
| #### Underscore (`_`) prefix/suffix | |
| An underscore prefix indicates a syntactically-required identifier will not be | |
| used. It is encouraged to provide a meaningful name after the underscore, but a | |
| standalone `_` is allowed. | |
| <div class='goodcode'></div> | |
| ```ts | |
| (_projectId, api) => of(!params.disabledApis.includes(api)); | |
| [].filter((_, i) => i % 2 === 0); | |
| for await (const _item of getAllTheThings()) { | |
| count++; | |
| } | |
| using _cleanupFoo = foo(); | |
| ``` | |
| Do not use this style for trailing unused parameters, those should be omitted. | |
| Trailing unused parameters are allowed on methods that are specifically intended | |
| to be overridden. | |
| <div class='badcode'></div> | |
| ```ts | |
| [].filter((element, _index) => !element.hasSomeProperty()); | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| [].filter(element => !element.hasSomeProperty()); | |
| ``` | |
| Identifiers must not use `_` as a suffix. | |
| > Tip: If you only need some of the elements from an array (or TypeScript | |
| > tuple), you can insert extra commas in a destructuring statement to ignore | |
| > in-between elements: | |
| > | |
| > ```ts | |
| > const [a, , b] = [1, 5, 10]; // a <- 1, b <- 10 | |
| > ``` | |
| <div class="numbered"></div> | |
| <a id="identifiers-imports"></a> | |
| #### Imports | |
| Module namespace imports are `lowerCamelCase` while files are `snake_case`, | |
| which means that imports correctly will not match in casing style, such as | |
| <div class='goodcode'></div> | |
| ```ts | |
| import * as fooBar from './foo_bar'; | |
| ``` | |
| Some libraries might commonly use a namespace import prefix that violates this | |
| naming scheme, but overbearingly common open source use makes the violating | |
| style more readable. The only libraries that currently fall under this exception | |
| are: | |
| * [jquery](https://jquery.com/), using the `$` prefix | |
| * [threejs](https://threejs.org/), using the `THREE` prefix | |
| <div class="numbered"></div> | |
| <a id="identifiers-constants"></a> | |
| #### Constants | |
| **Immutable**: `CONSTANT_CASE` indicates that a value is *intended* to not be | |
| changed, and *may* be used for values that can technically be modified (i.e. | |
| values that are not deeply frozen) to indicate to users that they must not be | |
| modified. | |
| <div class='goodcode'></div> | |
| ```ts | |
| const UNIT_SUFFIXES = { | |
| 'milliseconds': 'ms', | |
| 'seconds': 's', | |
| }; | |
| // Even though per the rules of JavaScript UNIT_SUFFIXES is | |
| // mutable, the uppercase shows users to not modify it. | |
| ``` | |
| A constant can also be a `static readonly` property of a class. | |
| <div class='goodcode'></div> | |
| ```ts | |
| class Foo { | |
| private static readonly MY_SPECIAL_NUMBER = 5; | |
| bar() { | |
| return 2 * Foo.MY_SPECIAL_NUMBER; | |
| } | |
| } | |
| ``` | |
| **Global**: Only symbols declared on the module level, static fields of module | |
| level classes, and values of module level enums, *may* use `CONST_CASE`. If a | |
| value can be instantiated more than once over the lifetime of the program (e.g. | |
| a local variable declared within a function, or a static field on a class nested | |
| in a function) then it *must* use `lowerCamelCase`. | |
| [Local-scope aliases](#aliases) are excepted and should use the format of the | |
| existing identifier. | |
| If a value is an arrow function that implements an interface, then it *may* be | |
| declared `lowerCamelCase`. | |
| <a id="naming-local-aliases"></a> | |
| <div class="numbered"></div> | |
| <a id="aliases"></a> | |
| #### Aliases | |
| When creating a local-scope alias of an existing symbol, use the format of the | |
| existing identifier. The local alias *must* match the existing naming and format | |
| of the source. For variables use `const` for your local aliases, and for class | |
| fields use the `readonly` attribute. | |
| > Note: If you're creating an alias just to expose it to a template in your | |
| > framework of choice, remember to also apply the proper | |
| > [access modifiers](#properties-used-outside-of-class-lexical-scope). | |
| <div class='goodcode'></div> | |
| ```ts | |
| const {BrewStateEnum} = SomeType; | |
| const CAPACITY = 5; | |
| class Teapot { | |
| readonly BrewStateEnum = BrewStateEnum; | |
| readonly CAPACITY = CAPACITY; | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="overridden-and-implemented-members"></a> | |
| #### Overridden and implemented members | |
| Properties and methods that override, implement, or narrow a base class or | |
| interface member, or appear in a contextually typed object literal, must match | |
| the existing declaration's name and casing to compile. Casing rules therefore | |
| apply only at a member's original declaration, which *must* follow them unless | |
| an external contract requires otherwise. Consider fixing the original | |
| declaration's name if possible. | |
| <div class='badcode'></div> | |
| ```ts | |
| interface ServerResponse { | |
| // Disallowed: property names must use lowerCamelCase (or CONSTANT_CASE). | |
| // The correct name here would be `errorCode`. | |
| error_code: number; | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // When the existing name is required to match an external contract, suppress | |
| // the lint warning on the original declaration and include a rationale: | |
| declare interface ServerResponse { | |
| // Required to match external contract. | |
| // tslint:disable-next-line:enforce-name-casing | |
| error_code: number; | |
| } | |
| // Extending, implementing, or contextually matching the existing declaration | |
| // is allowed to follow its naming convention without another suppression: | |
| interface ErrorResponse extends ServerResponse { | |
| error_code: 400 | 500; | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="type-system"></a> | |
| ## Type system | |
| <div class="numbered"></div> | |
| <a id="type-inference"></a> | |
| ### Type inference | |
| Code *may* rely on type inference as implemented by the TypeScript compiler for | |
| all type expressions (variables, fields, return types, etc). | |
| <div class='goodcode'></div> | |
| ```ts | |
| const x = 15; // Type inferred. | |
| ``` | |
| Leave out type annotations when types are trivially inferred: unexported | |
| variables or parameters initialized to a `string`, `number`, or `boolean` | |
| literal. Type annotations are not considered trivial on exported symbols where | |
| required to be compatible with `isolatedDeclarations`. | |
| <div class='badcode'></div> | |
| ```ts | |
| let count: number = 0; // Bad: type annotation here is redundant | |
| // Bad: Exported interpolation fails isolatedDeclarations. | |
| export const PATH = `/users/${id}`; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| let count = 0; | |
| // Good: Explicit type for isolatedDeclarations. | |
| export const PATH: string = `/users/${id}`; | |
| ``` | |
| Also leave out explicit generic types where they are redundant with the type | |
| annotation. | |
| <div class='badcode'></div> | |
| ```ts | |
| // Bad: Specifying '<string>' twice is unnecessary. | |
| const x: Set<string> = new Set<string>(); | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| const x = new Set<string>(); // Preferred when local | |
| export const y: Set<string> = new Set(); // Annotation required for exports | |
| ``` | |
| For more complex expressions, type annotations can help with readability of the | |
| program: | |
| <div class='badcode'></div> | |
| ```ts | |
| // Hard to reason about the type of 'value' without an annotation. | |
| const value = await rpc.getSomeValue().transform(); | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Can tell the type of 'value' at a glance. | |
| const value: string[] = await rpc.getSomeValue().transform(); | |
| ``` | |
| Whether an annotation is required is decided by the code reviewer. | |
| <div class="numbered"></div> | |
| <a id="return-types"></a> | |
| #### Return types | |
| Whether to include return type annotations for functions and methods is up to | |
| the code author. Reviewers *may* ask for annotations to clarify complex return | |
| types that are hard to understand. Projects *may* have a local policy to always | |
| require return types, but this is not a general TypeScript style requirement. | |
| There are two benefits to explicitly typing out the implicit return values of | |
| functions and methods: | |
| - More precise documentation to benefit readers of the code. | |
| - Surface potential type errors faster in the future if there are code changes | |
| that change the return type of the function. | |
| <a id="null-vs-undefined"></a> | |
| <div class="numbered"></div> | |
| <a id="undefined-and-null"></a> | |
| ### Undefined and null | |
| TypeScript supports `undefined` and `null` types. Nullable types can be | |
| constructed as a union type (`string|null`); similarly with `undefined`. There | |
| is no special syntax for unions of `undefined` and `null`. | |
| TypeScript code can use either `undefined` or `null` to denote absence of a | |
| value, there is no general guidance to prefer one over the other. Many | |
| JavaScript APIs use `undefined` (e.g. `Map.get`), while many DOM and Google APIs | |
| use `null` (e.g. `Element.getAttribute`), so the appropriate absent value | |
| depends on the context. | |
| <div class="numbered"></div> | |
| <a id="nullableundefined-type-aliases"></a> | |
| #### Nullable/undefined type aliases | |
| Type aliases *must not* include `|null` or `|undefined` in a union type. | |
| Nullable aliases typically indicate that null values are being passed around | |
| through too many layers of an application, and this clouds the source of the | |
| original issue that resulted in `null`. They also make it unclear when specific | |
| values on a class or interface might be absent. | |
| Instead, code *must* only add `|null` or `|undefined` when the alias is actually | |
| used. Code *should* deal with null values close to where they arise, using the | |
| below techniques. | |
| <div class='badcode'></div> | |
| ```ts | |
| // Bad | |
| type CoffeeResponse = Latte|Americano|undefined; | |
| class CoffeeService { | |
| getLatte(): CoffeeResponse { ... }; | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Better | |
| type CoffeeResponse = Latte|Americano; | |
| class CoffeeService { | |
| getLatte(): CoffeeResponse|undefined { ... }; | |
| } | |
| ``` | |
| <a id="structural-types-vs-nominal-types"></a> | |
| <div class="numbered"></div> | |
| <a id="use-structural-types"></a> | |
| ### Use structural types | |
| TypeScript's type system is structural, not nominal. That is, a value matches a | |
| type if it has at least all the properties the type requires and the properties' | |
| types match, recursively. | |
| When providing a structural-based implementation, explicitly include the type at | |
| the declaration of the symbol (this allows more precise type checking and error | |
| reporting). | |
| <div class='goodcode'></div> | |
| ```ts | |
| const foo: Foo = { | |
| a: 123, | |
| b: 'abc', | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| const badFoo = { | |
| a: 123, | |
| b: 'abc', | |
| } | |
| ``` | |
| Use interfaces to define structural types, not classes | |
| <div class='goodcode'></div> | |
| ```ts | |
| interface Foo { | |
| a: number; | |
| b: string; | |
| } | |
| const foo: Foo = { | |
| a: 123, | |
| b: 'abc', | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| class Foo { | |
| readonly a: number; | |
| readonly b: number; | |
| } | |
| const foo: Foo = { | |
| a: 123, | |
| b: 'abc', | |
| } | |
| ``` | |
| Why? | |
| The "badFoo" object above relies on type inference. Additional fields could be | |
| added to "badFoo" and the type is inferred based on the object itself. | |
| When passing a "badFoo" to a function that takes a "Foo", the error will be at | |
| the function call site, rather than at the object declaration site. This is also | |
| useful when changing the surface of an interface across broad codebases. | |
| ```ts | |
| interface Animal { | |
| sound: string; | |
| name: string; | |
| } | |
| function makeSound(animal: Animal) {} | |
| /** | |
| * 'cat' has an inferred type of '{sound: string}' | |
| */ | |
| const cat = { | |
| sound: 'meow', | |
| }; | |
| /** | |
| * 'cat' does not meet the type contract required for the function, so the | |
| * TypeScript compiler errors here, which may be very far from where 'cat' is | |
| * defined. | |
| */ | |
| makeSound(cat); | |
| /** | |
| * Horse has a structural type and the type error shows here rather than the | |
| * function call. 'horse' does not meet the type contract of 'Animal'. | |
| */ | |
| const horse: Animal = { | |
| sound: 'niegh', | |
| }; | |
| const dog: Animal = { | |
| sound: 'bark', | |
| name: 'MrPickles', | |
| }; | |
| makeSound(dog); | |
| makeSound(horse); | |
| ``` | |
| <a id="interfaces-vs-type-aliases"></a> | |
| <div class="numbered"></div> | |
| <a id="prefer-interfaces"></a> | |
| ### Prefer interfaces over type literal aliases | |
| TypeScript supports | |
| [type aliases](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-aliases) | |
| for naming a type expression. This can be used to name primitives, unions, | |
| tuples, and any other types. | |
| However, when declaring types for objects, use interfaces instead of a type | |
| alias for the object literal expression. | |
| <div class='goodcode'></div> | |
| ```ts | |
| interface User { | |
| firstName: string; | |
| lastName: string; | |
| } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| type User = { | |
| firstName: string, | |
| lastName: string, | |
| } | |
| ``` | |
| Why? | |
| These forms are nearly equivalent, so under the principle of just choosing one | |
| out of two forms to prevent variation, we should choose one. Additionally, there | |
| are also | |
| [interesting technical reasons to prefer interface](https://ncjamieson.com/prefer-interfaces/). | |
| That page quotes the TypeScript team lead: "Honestly, my take is that it should | |
| really just be interfaces for anything that they can model. There is no benefit | |
| to type aliases when there are so many issues around display/perf." | |
| <div class="numbered"></div> | |
| <a id="arrayt-type"></a> | |
| ### `Array<T>` Type | |
| For simple types (containing just alphanumeric characters and dot), use the | |
| syntax sugar for arrays, `T[]` or `readonly T[]`, rather than the longer form | |
| `Array<T>` or `ReadonlyArray<T>`. | |
| For multi-dimensional non-`readonly` arrays of simple types, use the syntax | |
| sugar form (`T[][]`, `T[][][]`, and so on) rather than the longer form. | |
| For anything more complex, use the longer form `Array<T>`. | |
| These rules apply at each level of nesting, i.e. a simple `T[]` nested in a more | |
| complex type would still be spelled as `T[]`, using the syntax sugar. | |
| <div class='goodcode'></div> | |
| ```ts | |
| let a: string[]; | |
| let b: readonly string[]; | |
| let c: ns.MyObj[]; | |
| let d: string[][]; | |
| let e: Array<{n: number, s: string}>; | |
| let f: Array<string|number>; | |
| let g: ReadonlyArray<string|number>; | |
| let h: InjectionToken<string[]>; // Use syntax sugar for nested types. | |
| let i: ReadonlyArray<string[]>; | |
| let j: Array<readonly string[]>; | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| let a: Array<string>; // The syntax sugar is shorter. | |
| let b: ReadonlyArray<string>; | |
| let c: Array<ns.MyObj>; | |
| let d: Array<string[]>; | |
| let e: {n: number, s: string}[]; // The braces make it harder to read. | |
| let f: (string|number)[]; // Likewise with parens. | |
| let g: readonly (string | number)[]; | |
| let h: InjectionToken<Array<string>>; | |
| let i: readonly string[][]; | |
| let j: (readonly string[])[]; | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="indexable-key-string-type"></a> | |
| ### Indexable types / index signatures (`{[key: string]: T}`) | |
| In JavaScript, it's common to use an object as an associative array (aka "map", | |
| "hash", or "dict"). Such objects can be typed using an | |
| [index signature](https://www.typescriptlang.org/docs/handbook/2/objects.html#index-signatures) | |
| (`[k: string]: T`) in TypeScript: | |
| ```ts | |
| const fileSizes: {[fileName: string]: number} = {}; | |
| fileSizes['readme.txt'] = 541; | |
| ``` | |
| In TypeScript, provide a meaningful label for the key. (The label only exists | |
| for documentation; it's unused otherwise.) | |
| <div class='badcode'></div> | |
| ```ts | |
| const users: {[key: string]: number} = ...; | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| const users: {[userName: string]: number} = ...; | |
| ``` | |
| > Rather than using one of these, consider using the ES6 `Map` and `Set` types | |
| > instead. JavaScript objects have | |
| > [surprising undesirable behaviors](http://2ality.com/2012/01/objects-as-maps.html) | |
| > and the ES6 types more explicitly convey your intent. Also, `Map`s can be | |
| > keyed by—and `Set`s can contain—types other than `string`. | |
| TypeScript's built-in `Record<Keys, ValueType>` type allows constructing types | |
| with a defined set of keys. This is distinct from associative arrays in that the | |
| keys are statically known. See advice on that | |
| [below](#mapped-conditional-types). | |
| <div class="numbered"></div> | |
| <a id="mapped-conditional-types"></a> | |
| ### Mapped and conditional types | |
| TypeScript's | |
| [mapped types](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html) | |
| and | |
| [conditional types](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html) | |
| allow specifying new types based on other types. TypeScript's standard library | |
| includes several type operators based on these (`Record`, `Partial`, `Readonly` | |
| etc). | |
| These type system features allow succinctly specifying types and constructing | |
| powerful yet type safe abstractions. They come with a number of drawbacks | |
| though: | |
| * Compared to explicitly specifying properties and type relations (e.g. using | |
| interfaces and extension, see below for an example), type operators require | |
| the reader to mentally evaluate the type expression. This can make programs | |
| substantially harder to read, in particular combined with type inference and | |
| expressions crossing file boundaries. | |
| * Mapped & conditional types' evaluation model, in particular when combined | |
| with type inference, is underspecified, not always well understood, and | |
| often subject to change in TypeScript compiler versions. Code can | |
| "accidentally" compile or seem to give the right results. This increases | |
| future support cost of code using type operators. | |
| * Mapped & conditional types are most powerful when deriving types from | |
| complex and/or inferred types. On the flip side, this is also when they are | |
| most prone to create hard to understand and maintain programs. | |
| * Some language tooling does not work well with these type system features. | |
| E.g. your IDE's find references (and thus rename property refactoring) will | |
| not find properties in a `Pick<T, Keys>` type, and Code Search won't | |
| hyperlink them. * | |
| The style recommendation is: | |
| * Always use the simplest type construct that can possibly express your code. | |
| * A little bit of repetition or verbosity is often much cheaper than the long | |
| term cost of complex type expressions. | |
| * Mapped & conditional types may be used, subject to these considerations. | |
| For example, TypeScript's built-in `Pick<T, Keys>` type allows creating a new | |
| type by subsetting another type `T`, but simple interface extension can often be | |
| easier to understand. | |
| ```ts | |
| interface User { | |
| shoeSize: number; | |
| favoriteIcecream: string; | |
| favoriteChocolate: string; | |
| } | |
| // FoodPreferences has favoriteIcecream and favoriteChocolate, but not shoeSize. | |
| type FoodPreferences = Pick<User, 'favoriteIcecream'|'favoriteChocolate'>; | |
| ``` | |
| This is equivalent to spelling out the properties on `FoodPreferences`: | |
| ```ts | |
| interface FoodPreferences { | |
| favoriteIcecream: string; | |
| favoriteChocolate: string; | |
| } | |
| ``` | |
| To reduce duplication, `User` could extend `FoodPreferences`, or (possibly | |
| better) nest a field for food preferences: | |
| <div class='goodcode'></div> | |
| ```ts | |
| interface FoodPreferences { /* as above */ } | |
| interface User extends FoodPreferences { | |
| shoeSize: number; | |
| // also includes the preferences. | |
| } | |
| ``` | |
| Using interfaces here makes the grouping of properties explicit, improves IDE | |
| support, allows better optimization, and arguably makes the code easier to | |
| understand. | |
| <div class="numbered"></div> | |
| <a id="any"></a> | |
| ### `any` Type | |
| TypeScript's `any` type is a super and subtype of all other types, and allows | |
| dereferencing all properties. As such, `any` is dangerous - it can mask severe | |
| programming errors, and its use undermines the value of having static types in | |
| the first place. | |
| **Consider *not* to use `any`.** In circumstances where you want to use `any`, | |
| consider one of: | |
| - [Provide a more specific type](#any-specific) | |
| - [Use `unknown`](#any-unknown) | |
| - [Suppress the lint warning and document why](#any-suppress) | |
| <div class="numbered"></div> | |
| <a id="any-specific"></a> | |
| #### Providing a more specific type | |
| Use interfaces , an inline object type, or a type alias: | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Use declared interfaces to represent server-side JSON. | |
| declare interface MyUserJson { | |
| name: string; | |
| email: string; | |
| } | |
| // Use type aliases for types that are repetitive to write. | |
| type MyType = number|string; | |
| // Or use inline object types for complex returns. | |
| function getTwoThings(): {something: number, other: string} { | |
| // ... | |
| return {something, other}; | |
| } | |
| // Use a generic type, where otherwise a library would say `any` to represent | |
| // they don't care what type the user is operating on (but note "Return type | |
| // only generics" below). | |
| function nicestElement<T>(items: T[]): T { | |
| // Find the nicest element in items. | |
| // Code can also put constraints on T, e.g. <T extends HTMLElement>. | |
| } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="any-unknown"></a> | |
| #### Using `unknown` over `any` | |
| The `any` type allows assignment into any other type and dereferencing any | |
| property off it. Often this behaviour is not necessary or desirable, and code | |
| just needs to express that a type is unknown. Use the built-in type `unknown` in | |
| that situation — it expresses the concept and is much safer as it does not allow | |
| dereferencing arbitrary properties. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // Can assign any value (including null or undefined) into this but cannot | |
| // use it without narrowing the type or casting. | |
| const val: unknown = value; | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| const danger: any = value /* result of an arbitrary expression */; | |
| danger.whoops(); // This access is completely unchecked! | |
| ``` | |
| To safely use `unknown` values, narrow the type using a | |
| [type guard](https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types) | |
| <div class="numbered"></div> | |
| <a id="any-suppress"></a> | |
| #### Suppressing `any` lint warnings | |
| Sometimes using `any` is legitimate, for example in tests to construct a mock | |
| object. In such cases, add a comment that suppresses the lint warning, and | |
| document why it is legitimate. | |
| <div class='goodcode'></div> | |
| ```ts | |
| // This test only needs a partial implementation of BookService, and if | |
| // we overlooked something the test will fail in an obvious way. | |
| // This is an intentionally unsafe partial mock | |
| // tslint:disable-next-line:no-any | |
| const mockBookService = ({get() { return mockBook; }} as any) as BookService; | |
| // Shopping cart is not used in this test | |
| // tslint:disable-next-line:no-any | |
| const component = new MyComponent(mockBookService, /* unused ShoppingCart */ null as any); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="empty-interface-type"></a> | |
| ### `{}` Type | |
| The `{}` type, also known as an *empty interface* type, represents an interface | |
| with no properties. An empty interface type has no specified properties and | |
| therefore any non-nullish value is assignable to it. | |
| <div class='badcode'></div> | |
| ```ts | |
| let player: {}; | |
| player = { | |
| health: 50, | |
| }; // Allowed. | |
| console.log(player.health) // Property 'health' does not exist on type '{}'. | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| function takeAnything(obj:{}) { | |
| } | |
| takeAnything({}); | |
| takeAnything({ a: 1, b: 2 }); | |
| ``` | |
| Google3 code **should not** use `{}` for most use cases. `{}` represents any | |
| non-nullish primitive or object type, which is rarely appropriate. Prefer one of | |
| the following more-descriptive types: | |
| * `unknown` can hold any value, including `null` or `undefined`, and is | |
| generally more appropriate for opaque values. | |
| * `Record<string, T>` is better for dictionary-like objects, and provides | |
| better type safety by being explicit about the type `T` of contained values | |
| (which may itself be `unknown`). | |
| * `object` excludes primitives as well, leaving only non-nullish functions and | |
| objects, but without any other assumptions about what properties may be | |
| available. | |
| <div class="numbered"></div> | |
| <a id="tuple-types"></a> | |
| ### Tuple types | |
| If you are tempted to create a Pair type, instead use a tuple type: | |
| <div class='badcode'></div> | |
| ```ts | |
| interface Pair { | |
| first: string; | |
| second: string; | |
| } | |
| function splitInHalf(input: string): Pair { | |
| ... | |
| return {first: x, second: y}; | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| function splitInHalf(input: string): [string, string] { | |
| ... | |
| return [x, y]; | |
| } | |
| // Use it like: | |
| const [leftHalf, rightHalf] = splitInHalf('my string'); | |
| ``` | |
| However, often it's clearer to provide meaningful names for the properties. | |
| If declaring an `interface` is too heavyweight, you can use an inline object | |
| literal type: | |
| <div class='goodcode'></div> | |
| ```ts | |
| function splitHostPort(address: string): {host: string, port: number} { | |
| ... | |
| } | |
| // Use it like: | |
| const address = splitHostPort(userAddress); | |
| use(address.port); | |
| // You can also get tuple-like behavior using destructuring: | |
| const {host, port} = splitHostPort(userAddress); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="wrapper-types"></a> | |
| ### Wrapper types | |
| There are a few types related to JavaScript primitives that *should not* ever be | |
| used: | |
| - `String`, `Boolean`, and `Number` have slightly different meaning from the | |
| corresponding primitive types `string`, `boolean`, and `number`. Always use | |
| the lowercase version. | |
| - `Object` has similarities to both `{}` and `object`, but is slightly looser. | |
| Use `{}` for a type that include everything except `null` and `undefined`, | |
| or lowercase `object` to further exclude the other primitive types (the | |
| three mentioned above, plus `symbol` and `bigint`). | |
| Further, never invoke the wrapper types as constructors (with `new`). | |
| <div class="numbered"></div> | |
| <a id="return-type-only-generics"></a> | |
| ### Return type only generics | |
| Avoid creating APIs that have return type only generics. When working with | |
| existing APIs that have return type only generics always explicitly specify the | |
| generics. | |
| <a id="appendices-style-related-tools"></a> | |
| <div class="numbered"></div> | |
| <a id="toolchain-requirements"></a> | |
| ## Toolchain requirements | |
| Google style requires using a number of tools in specific ways, outlined here. | |
| <a id="google-format"></a> | |
| <a id="use-the-google3-formatter"></a> | |
| <a id="source-code-formatting"></a> | |
| <a id="appendices-clang-format"></a> | |
| <a id="formatting"></a> | |
| <a id="formatting-array-literals"></a> | |
| <a id="formatting-block-indentation"></a> | |
| <a id="formatting-column-limit"></a> | |
| <a id="formatting-empty-blocks"></a> | |
| <a id="formatting-function-expressions"></a> | |
| <a id="formatting-nonempty-blocks"></a> | |
| <a id="formatting-object-literals"></a> | |
| <a id="formatting-one-statement-perline"></a> | |
| <a id="formatting-statements"></a> | |
| <a id="formatting-switch-statements"></a> | |
| <a id="formatting-vertical-whitespace"></a> | |
| <a id="formatting-whitespace"></a> | |
| <div class="numbered"></div> | |
| <a id="typescript-compiler"></a> | |
| ### TypeScript compiler | |
| All TypeScript files must pass type checking using the standard tool chain. | |
| <div class="numbered"></div> | |
| <a id="ts-ignore"></a> | |
| #### @ts-ignore | |
| Do not use `@ts-ignore` nor the variants `@ts-expect-error` or `@ts-nocheck`. | |
| Why? | |
| They superficially seem to be an easy way to "fix" a compiler error, but in | |
| practice, a specific compiler error is often caused by a larger problem that can | |
| be fixed more directly. | |
| For example, if you are using `@ts-ignore` to suppress a type error, then it's | |
| hard to predict what types the surrounding code will end up seeing. For many | |
| type errors, the advice in [how to best use `any`](#any) is useful. | |
| You may use `@ts-expect-error` in unit tests, though you generally *should not*. | |
| `@ts-expect-error` suppresses all errors. It's easy to accidentally over-match | |
| and suppress more serious errors. Consider one of: | |
| - When testing APIs that need to deal with unchecked values at runtime, add | |
| casts to the expected type or to `any` and add an explanatory comment. This | |
| limits error suppression to a single expression. | |
| - Suppress the lint warning and document why, similar to | |
| [suppressing `any` lint warnings](#any-suppress). | |
| <a id="appendices-conformance-framework"></a> | |
| <div class="numbered"></div> | |
| <a id="conformance"></a> | |
| ### Conformance | |
| Google TypeScript includes several *conformance frameworks*, | |
| [tsetse](https://tsetse.info) and [tsec](https://github.com/google/tsec). | |
| These rules are commonly used to enforce critical restrictions (such as defining | |
| globals, which could break the codebase) and security patterns (such as using | |
| `eval` or assigning to `innerHTML`), or more loosely to improve code quality. | |
| Google-style TypeScript must abide by any applicable global or framework-local | |
| conformance rules. | |
| <a id="jsdoc"></a> | |
| <a id="formatting-comments"></a> | |
| <div class="numbered"></div> | |
| <a id="comments-documentation"></a> | |
| ## Comments and documentation | |
| <div class="numbered"></div> | |
| <a id="jsdoc-vs-comments"></a> | |
| #### JSDoc versus comments | |
| There are two types of comments, JSDoc (`/** ... */`) and non-JSDoc ordinary | |
| comments (`// ...` or `/* ... */`). | |
| * Use `/** JSDoc */` comments for documentation, i.e. comments a user of the | |
| code should read. | |
| * Use `// line comments` for implementation comments, i.e. comments that only | |
| concern the implementation of the code itself. | |
| JSDoc comments are understood by tools (such as editors and documentation | |
| generators), while ordinary comments are only for other humans. | |
| <a id="formatting-block-comment-style"></a> | |
| <div class="numbered"></div> | |
| <a id="multi-line-comments"></a> | |
| #### Multi-line comments | |
| Multi-line comments are indented at the same level as the surrounding code. They | |
| *must* use multiple single-line comments (`//`-style), not block comment style | |
| (`/* */`). | |
| <div class='goodcode'></div> | |
| ```ts | |
| // This is | |
| // fine | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| /* | |
| * This should | |
| * use multiple | |
| * single-line comments | |
| */ | |
| /* This should use // */ | |
| ``` | |
| Comments are not enclosed in boxes drawn with asterisks or other characters. | |
| <div class="numbered"></div> | |
| <a id="jsdoc-general-form"></a> | |
| ### JSDoc general form | |
| The basic formatting of JSDoc comments is as seen in this example: | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** | |
| * Multiple lines of JSDoc text are written here, | |
| * wrapped normally. | |
| * @param arg A number to do something to. | |
| */ | |
| function doSomething(arg: number) { … } | |
| ``` | |
| or in this single-line example: | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** This short jsdoc describes the function. */ | |
| function doSomething(arg: number) { … } | |
| ``` | |
| If a single-line comment overflows into multiple lines, it *must* use the | |
| multi-line style with `/**` and `*/` on their own lines. | |
| Many tools extract metadata from JSDoc comments to perform code validation and | |
| optimization. As such, these comments *must* be well-formed. | |
| <div class="numbered"></div> | |
| <a id="jsdoc-markdown"></a> | |
| ### Markdown | |
| JSDoc is written in Markdown, though it *may* include HTML when necessary. | |
| This means that tooling parsing JSDoc will ignore plain text formatting, so if | |
| you did this: | |
| <div class='badcode'></div> | |
| ```ts | |
| /** | |
| * Computes weight based on three factors: | |
| * items sent | |
| * items received | |
| * last timestamp | |
| */ | |
| ``` | |
| it will be rendered like this: | |
| ``` | |
| Computes weight based on three factors: items sent items received last timestamp | |
| ``` | |
| Instead, write a Markdown list: | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** | |
| * Computes weight based on three factors: | |
| * | |
| * - items sent | |
| * - items received | |
| * - last timestamp | |
| */ | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="jsdoc-tags"></a> | |
| ### JSDoc tags | |
| Google style allows a subset of JSDoc tags. Most tags must occupy their own | |
| line, with the tag at the beginning of the line. | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** | |
| * The "param" tag must occupy its own line and may not be combined. | |
| * @param left A description of the left param. | |
| * @param right A description of the right param. | |
| */ | |
| function add(left: number, right: number) { ... } | |
| ``` | |
| <div class='badcode'></div> | |
| ```ts | |
| /** | |
| * The "param" tag must occupy its own line and may not be combined. | |
| * @param left @param right | |
| */ | |
| function add(left: number, right: number) { ... } | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="jsdoc-line-wrapping"></a> | |
| ### Line wrapping | |
| Line-wrapped block tags are indented four spaces. Wrapped description text *may* | |
| be lined up with the description on previous lines, but this horizontal | |
| alignment is discouraged. | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** | |
| * Illustrates line wrapping for long param/return descriptions. | |
| * @param foo This is a param with a particularly long description that just | |
| * doesn't fit on one line. | |
| * @return This returns something that has a lengthy description too long to fit | |
| * in one line. | |
| */ | |
| exports.method = function(foo) { | |
| return 5; | |
| }; | |
| ``` | |
| Do not indent when wrapping a `@desc` or `@fileoverview` description. | |
| <div class="numbered"></div> | |
| <a id="document-all-top-level-exports-of-modules"></a> | |
| ### Document all top-level exports of modules | |
| Use `/** JSDoc */` comments to communicate information to the users of your | |
| code. Avoid merely restating the property or parameter name. You *should* also | |
| document all properties and methods (exported/public or not) whose purpose is | |
| not immediately obvious from their name, as judged by your reviewer. | |
| **Exception:** Symbols that are only exported to be consumed by tooling, such as | |
| @NgModule classes, do not require comments. | |
| <div class="numbered"></div> | |
| <a id="jsdoc-class-comments"></a> | |
| ### Class comments | |
| JSDoc comments for classes should provide the reader with enough information to | |
| know how and when to use the class, as well as any additional considerations | |
| necessary to correctly use the class. Textual descriptions may be omitted on the | |
| constructor. | |
| <div class="numbered"></div> | |
| <a id="method-and-function-comments"></a> | |
| ### Method and function comments | |
| Method, parameter, and return descriptions may be omitted if they are obvious | |
| from the rest of the method’s JSDoc or from the method name and type signature. | |
| Method descriptions begin with a verb phrase that describes what the method | |
| does. This phrase is not an imperative sentence, but instead is written in the | |
| third person, as if there is an implied "This method ..." before it. | |
| <div class="numbered"></div> | |
| <a id="parameter-property-comments"></a> | |
| ### Parameter property comments | |
| A | |
| [parameter property](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties) | |
| is a constructor parameter that is prefixed by one of the modifiers `private`, | |
| `protected`, `public`, or `readonly`. A parameter property declares both a | |
| parameter and an instance property, and implicitly assigns into it. For example, | |
| `constructor(private readonly foo: Foo)`, declares that the constructor takes a | |
| parameter `foo`, but also declares a private readonly property `foo`, and | |
| assigns the parameter into that property before executing the remainder of the | |
| constructor. | |
| To document these fields, use JSDoc's `@param` annotation. Editors display the | |
| description on constructor calls and property accesses. | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** This class demonstrates how parameter properties are documented. */ | |
| class ParamProps { | |
| /** | |
| * @param percolator The percolator used for brewing. | |
| * @param beans The beans to brew. | |
| */ | |
| constructor( | |
| private readonly percolator: Percolator, | |
| private readonly beans: CoffeeBean[]) {} | |
| } | |
| ``` | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** This class demonstrates how ordinary fields are documented. */ | |
| class OrdinaryClass { | |
| /** The bean that will be used in the next call to brew(). */ | |
| nextBean: CoffeeBean; | |
| constructor(initialBean: CoffeeBean) { | |
| this.nextBean = initialBean; | |
| } | |
| } | |
| ``` | |
| <a id="omit-comments-that-are-redundant-with-typescript"></a> | |
| <a id="do-not-use-override"></a> | |
| <div class="numbered"></div> | |
| <a id="jsdoc-type-annotations"></a> | |
| ### JSDoc type annotations | |
| JSDoc type annotations are redundant in TypeScript source code. Do not declare | |
| types in `@param` or `@return` blocks, do not write `@implements`, `@enum`, | |
| `@private`, `@override` etc. on code that uses the `implements`, `enum`, | |
| `private`, `override` etc. keywords. | |
| <div class="numbered"></div> | |
| <a id="redundant-comments"></a> | |
| ### Make comments that actually add information | |
| For non-exported symbols, sometimes the name and type of the function or | |
| parameter is enough. Code will *usually* benefit from more documentation than | |
| just variable names though! | |
| * Avoid comments that just restate the parameter name and type, e.g. | |
| <div class='badcode'></div> | |
| ```ts | |
| /** @param fooBarService The Bar service for the Foo application. */ | |
| ``` | |
| * Because of this rule, `@param` and `@return` lines are only required when | |
| they add information, and *may* otherwise be omitted. | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** | |
| * POSTs the request to start coffee brewing. | |
| * @param amountLitres The amount to brew. Must fit the pot size! | |
| */ | |
| brew(amountLitres: number, logger: Logger) { | |
| // ... | |
| } | |
| ``` | |
| <a id="formatting-param-name-comments"></a> | |
| <div class="numbered"></div> | |
| <a id="comments-when-calling-a-function"></a> | |
| #### Comments when calling a function | |
| “Parameter name” comments should be used whenever the method name and parameter | |
| value do not sufficiently convey the meaning of the parameter. | |
| Before adding these comments, consider refactoring the method to instead accept | |
| an interface and destructure it to greatly improve call-site readability. | |
| "Parameter name" comments go before the parameter value, and include the | |
| parameter name and a `=` suffix: | |
| <div class='goodcode'></div> | |
| ```ts | |
| someFunction(obviousParam, /* shouldRender= */ true, /* name= */ 'hello'); | |
| ``` | |
| Existing code may use a legacy parameter name comment style, which places these | |
| comments ~after~ the parameter value and omits the `=`. Continuing to use this | |
| style within the file for consistency is acceptable. | |
| ```ts | |
| someFunction(obviousParam, true /* shouldRender */, 'hello' /* name */); | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="place-documentation-prior-to-decorators"></a> | |
| ### Place documentation prior to decorators | |
| When a class, method, or property have both decorators like `@Component` and | |
| JsDoc, please make sure to write the JsDoc before the decorator. | |
| * Do not write JsDoc between the Decorator and the decorated statement. | |
| <div class='badcode'></div> | |
| ```ts | |
| @Component({ | |
| selector: 'foo', | |
| template: 'bar', | |
| }) | |
| /** Component that prints "bar". */ | |
| export class FooComponent {} | |
| ``` | |
| * Write the JsDoc block before the Decorator. | |
| <div class='goodcode'></div> | |
| ```ts | |
| /** Component that prints "bar". */ | |
| @Component({ | |
| selector: 'foo', | |
| template: 'bar', | |
| }) | |
| export class FooComponent {} | |
| ``` | |
| <div class="numbered"></div> | |
| <a id="policies"></a> | |
| ## Policies | |
| <a id="policies-be-consistent"></a> | |
| <a id="policies-newly-added-code-use-google-style"></a> | |
| <div class="numbered"></div> | |
| <a id="consistency"></a> | |
| ### Consistency | |
| For any style question that isn't settled definitively by this specification, do | |
| what the other code in the same file is already doing ("be consistent"). If that | |
| doesn't resolve the question, consider emulating the other files in the same | |
| directory. | |
| Brand new files *must* use Google Style, regardless of the style choices of | |
| other files in the same package. When adding new code to a file that is not in | |
| Google Style, reformatting the existing code first is recommended, subject to | |
| the advice [below](#reformatting-existing-code). If this reformatting is not | |
| done, then new code *should* be as consistent as possible with existing code in | |
| the same file, but *must not* violate the style guide. | |
| <a id="policies-code-not-in-google-style"></a> | |
| <a id="policies-reformatting-existing-code"></a> | |
| <div class="numbered"></div> | |
| <a id="reformatting-existing-code"></a> | |
| #### Reformatting existing code | |
| You will occasionally encounter files in the codebase that are not in proper | |
| Google Style. These may have come from an acquisition, or may have been written | |
| before Google Style took a position on some issue, or may be in non-Google Style | |
| for any other reason. | |
| When updating the style of existing code, follow these guidelines. | |
| 1. It is not required to change all existing code to meet current style | |
| guidelines. Reformatting existing code is a trade-off between code churn and | |
| consistency. Style rules evolve over time and these kinds of tweaks to | |
| maintain compliance would create unnecessary churn. However, if significant | |
| changes are being made to a file it is expected that the file will be in | |
| Google Style. | |
| 1. Be careful not to allow opportunistic style fixes to muddle the focus of a | |
| CL. If you find yourself making a lot of style changes that aren’t critical | |
| to the central focus of a CL, promote those changes to a separate CL. | |
| <a id="policies-deprecation"></a> | |
| <div class="numbered"></div> | |
| <a id="deprecation"></a> | |
| ### Deprecation | |
| Mark deprecated methods, classes or interfaces with an `@deprecated` JSDoc | |
| annotation. A deprecation comment must include simple, clear directions for | |
| people to fix their call sites. | |
| <a id="policies-generated-code-mostly-exempt"></a> | |
| <div class="numbered"></div> | |
| <a id="generated-code"></a> | |
| ### Generated code: mostly exempt | |
| Source code generated by the build process is not required to be in Google | |
| Style. However, any generated identifiers that will be referenced from | |
| hand-written source code must follow the naming requirements. As a special | |
| exception, such identifiers are allowed to contain underscores, which may help | |
| to avoid conflicts with hand-written identifiers. | |
| <a id="goals"></a> | |
| <div class="numbered"></div> | |
| <a id="style-guide-goals"></a> | |
| #### Style guide goals | |
| In general, engineers usually know best about what's needed in their code, so if | |
| there are multiple options and the choice is situation dependent, we should let | |
| decisions be made locally. So the default answer should be "leave it out". | |
| The following points are the exceptions, which are the reasons we have some | |
| global rules. Evaluate your style guide proposal against the following: | |
| 1. **Code should avoid patterns that are known to cause problems, especially | |
| for users new to the language.** | |
| 2. **Code across projects should be consistent across irrelevant variations.** | |
| When there are two options that are equivalent in a superficial way, we | |
| should consider choosing one just so we don't divergently evolve for no | |
| reason and avoid pointless debates in code reviews. | |
| Examples: | |
| - The capitalization style of names. | |
| - `x as T` syntax vs the equivalent `<T>x` syntax (disallowed). | |
| - `Array<[number, number]>` vs `[number, number][]`. | |
| 3. **Code should be maintainable in the long term.** | |
| Code usually lives longer than the original author works on it, and the | |
| TypeScript team must keep all of Google working into the future. | |
| Examples: | |
| - We use software to automate changes to code, so code is autoformatted so | |
| it's easy for software to meet whitespace rules. | |
| - We require a single set of compiler flags, so a given TS library can be | |
| written assuming a specific set of flags, and users can always safely | |
| use a shared library. | |
| - Code must import the libraries it uses ("strict deps") so that a | |
| refactor in a dependency doesn't change the dependencies of its users. | |
| - We ask users to write tests. Without tests we cannot have confidence | |
| that changes that we make to the language, don't break users. | |
| 4. **Code reviewers should be focused on improving the quality of the code, not | |
| enforcing arbitrary rules.** | |
| If it's possible to implement your rule as an automated check that is often | |
| a good sign. This also supports principle 3. | |
| If it really just doesn't matter that much -- if it's an obscure corner of | |
| the language or if it avoids a bug that is unlikely to occur -- it's | |
| probably worth leaving out. |