TypeScript StyleGuide and Coding Conventions

An unofficial TypeScript StyleGuide

People have asked me for my opinions on this. Personally I don’t enforce these a lot on my teams and projects but it does help to have these mentioned as a tie breaker when someone feels the need to have such strong consistency. There are other things that I feel much more strongly about and those are covered in the tips chapter (e.g. type assertion is bad, property setters are bad) ?.

Key Sections:

Variable and Function

  • Use camelCase for variable and function names

Reason: Conventional JavaScript

Bad

  1. var FooVar;
  2. function BarFunc() { }

Good

  1. var fooVar;
  2. function barFunc() { }

Class

  • Use PascalCase for class names.

Reason: This is actually fairly conventional in standard JavaScript.

Bad

  1. class foo { }

Good

  1. class Foo { }
  • Use camelCase of class members and methods

Reason: Naturally follows from variable and function naming convention.

Bad

  1. class Foo {
  2.     Bar: number;
  3.     Baz() { }
  4. }

Good

  1. class Foo {
  2.     bar: number;
  3.     baz() { }
  4. }

Interface

  • Use PascalCase for name.

Reason: Similar to class

  • Use camelCase for members.

Reason: Similar to class

  • Don’t prefix with I

Reason: Unconventional. lib.d.ts defines important interfaces without an I (e.g. Window, Document etc).

Bad

  1. interface IFoo {
  2. }

Good

  1. interface Foo {
  2. }

Type

  • Use PascalCase for name.

Reason: Similar to class

  • Use camelCase for members.

Reason: Similar to class

Namespace

  • Use PascalCase for names

Reason: Convention followed by the TypeScript team. Namespaces are effectively just a class with static members. Class names are PascalCase => Namespace names are PascalCase

Bad

  1. namespace foo {
  2. }

Good

  1. namespace Foo {
  2. }

Enum

  • Use PascalCase for enum names

Reason: Similar to Class. Is a Type.

Bad

  1. enum color {
  2. }

Good

  1. enum Color {
  2. }
  • Use PascalCase for enum member

Reason: Convention followed by TypeScript team i.e. the language creators e.g SyntaxKind.StringLiteral. Also helps with translation (code generation) of other languages into TypeScript.

Bad

  1. enum Color {
  2.     red
  3. }

Good

  1. enum Color {
  2.     Red
  3. }

Null vs. Undefined

  • Prefer not to use either for explicit unavailability

Reason: these values are commonly used to keep a consistent structure between values. In TypeScript you use types to denote the structure

Bad

  1. let foo = {x:123,y:undefined};

Good

  1. let foo:{x:number,y?:number} = {x:123};
  • Use undefined in general (do consider returning an object like {valid:boolean,value?:Foo} instead)

Bad

  1. return null;

Good

  1. return undefined;
  • Use null where its a part of the API or conventional

Reason: It is conventional in Node.js e.g. error is null for NodeBack style callbacks.

Bad

  1. cb(undefined)

Good

  1. cb(null)
  • Use truthy check for objects being null or undefined

Bad

  1. if (error === null)

Good

  1. if (error)
  • Use == undefined / != undefined (not === / !==) to check for null / undefined on primitives as it works for both null/undefined but not other falsy values (like '',0,false) e.g.

Bad

  1. if (error !== null)

Good

  1. if (error != undefined)

Formatting

The TypeScript compiler ships with a very nice formatting language service. Whatever output it gives by default is good enough to reduce the cognitive overload on the team.

Use tsfmt to automatically format your code on the command line. Also your IDE (atom/vscode/vs/sublime) already has formatting support built-in.

Examples:

  1. // Space before type i.e. foo:<space>string
  2. const foo: string = "hello";

Quotes

  • Prefer single quotes (') unless escaping.

Reason: More JavaScript teams do this (e.g. airbnb, standard, npm, node, google/angular, facebook/react). Its easier to type (no shift needed on most keyboards). Prettier team recommends single quotes as well

Double quotes are not without merit: Allows easier copy paste of objects into JSON. Allows people to use other languages to work without changing their quote character. Allows you to use apostrophes e.g. He's not going.. But I’d rather not deviate from where the JS Community is fairly decided.

  • When you can’t use double quotes, try using back ticks (`).

Reason: These generally represent the intent of complex enough strings.

Spaces

  • Use 2 spaces. Not tabs.

Reason: More JavaScript teams do this (e.g. airbnb, idiomatic, standard, npm, node, google/angular, facebook/react). The TypeScript/VSCode teams use 4 spaces but are definitely the exception in the ecosystem.

Semicolons

  • Use semicolons.

Reasons: Explicit semicolons helps language formatting tools give consistent results. Missing ASI (automatic semicolon insertion) can trip new devs e.g. foo() \n (function(){}) will be a single statement (not two). Recommended by TC39 as well.

Array

  • Annotate arrays as foos:Foo[] instead of foos:Array<Foo>.

Reasons: Its easier to read. Its used by the TypeScript team. Makes easier to know something is an array as the mind is trained to detect [].

Filename

Name files with camelCase. E.g. accordian.tsx, myControl.tsx, utils.ts, map.ts etc.

Reason: Conventional across many JS teams.

type vs. interface

  • Use type when you might need a union or intersection:
  1. type Foo = number | { someProperty: number }
  • Use interface when you want extends or implements e.g
  1. interface Foo {
  2.   foo: string;
  3. }
  4. interface FooBar extends Foo {
  5.   bar: string;
  6. }
  7. class X implements FooBar {
  8.   foo: string;
  9.   bar: string;
  10. }
  • Otherwise use whatever makes you happy that day.