clean-code-typescript/README.md

clean-code-typescript

Clean Code concepts adapted for TypeScript.
Inspired from clean-code-javascript

Table of Contents

1. Introduction
2. Variables
3. Functions TODO
4. Objects and Data Structures
5. Classes TODO
6. SOLID TODO
7. Testing TODO
8. Concurrency
9. Error Handling TODO
10. Formatting TODO
11. Comments

Introduction

Software engineering principles, from Robert C. Martin's book Clean Code, adapted for TypeScript. This is not a style guide. It's a guide to producing readable, reusable, and refactorable software in TypeScript.

Not every principle herein has to be strictly followed, and even fewer will be universally agreed upon. These are guidelines and nothing more, but they are ones codified over many years of collective experience by the authors of Clean Code.

Our craft of software engineering is just a bit over 50 years old, and we are still learning a lot. When software architecture is as old as architecture itself, maybe then we will have harder rules to follow. For now, let these guidelines serve as a touchstone by which to assess the quality of the JavaScript code that you and your team produce.

One more thing: knowing these won't immediately make you a better software developer, and working with them for many years doesn't mean you won't make mistakes. Every piece of code starts as a first draft, like wet clay getting shaped into its final form. Finally, we chisel away the imperfections when we review it with our peers. Don't beat yourself up for first drafts that need improvement. Beat up the code instead!

⬆ back to top

Variables

Use meaningful variable names

Distinguish names in such a way that the reader knows what the differences offer.

Bad:

function between<T>(a1: T, a2: T, a3: T) {
  return a2 <= a1 && a1 <= a3;
}

Good:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}

⬆ back to top

Use pronounceable variable names

If you can’t pronounce it, you can’t discuss it without sounding like an idiot.

Bad:

class DtaRcrd102 {
  private genymdhms: Date;
  private modymdhms: Date;
  private pszqint = '102';
}

Good:

class Customer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}

Use the same vocabulary for the same type of variable

Bad:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;

Good:

function getUser(): User;

⬆ back to top

Use searchable names

We will read more code than we will ever write. It's important that the code we do write is readable and searchable. By not naming variables that end up being meaningful for understanding our program, we hurt our readers. Make your names searchable. Tools like TSLint can help identify unnamed constants.

Bad:

// What the heck is 86400000 for?
setTimeout(restart, 86400000);

Good:

// Declare them as capitalized named constants.
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;

setTimeout(restart, MILLISECONDS_IN_A_DAY);

⬆ back to top

Use explanatory variables

Bad:

declare const users:Map<string, User>;

for (const keyValue of users) {
  // iterate through users map
}

Good:

declare const users:Map<string, User>;

for (const [id, user] of users) {
  // iterate through users map
}

⬆ back to top

Avoid Mental Mapping

Explicit is better than implicit.
Clarity is king.

Bad:

const u = getUser();
const s = getSubscription();
const t = charge(u, s);

Good:

const user = getUser();
const subscription = getSubscription();
const transaction = charge(user, subscription);

⬆ back to top

Don't add unneeded context

If your class/object name tells you something, don't repeat that in your variable name.

Bad:

class Car {
  carMake: string;
  carModel: string;
  carColor: string;

  name(): string{
    return `${this.carMake} ${this.carModel} (${this.carColor})`;
  }
}

Good:

class Car {
  make: string;
  model: string;
  color: string;

  name(): string{
    return `${this.make} ${this.model} (${this.color})`;
  }
}

⬆ back to top

Use default arguments instead of short circuiting or conditionals

Default arguments are often cleaner than short circuiting.

Bad:

function loadPages(count: number) {
  const loadCount = count || 10;
}

Good:

function loadPages(count: number = 10) {
}

⬆ back to top

Objects and Data Structures

Use getters and setters

TypeScript supports getter/setter syntax. Using getters and setters to access data from objects that encapsulate behavior could be better that simply looking for a property on an object. "Why?" you might ask. Well, here's a list of reasons:

• When you want to do more beyond getting an object property, you don't have to look up and change every accessor in your codebase.
• Makes adding validation simple when doing a set.
• Encapsulates the internal representation.
• Easy to add logging and error handling when getting and setting.
• You can lazy load your object's properties, let's say getting it from a server.

Bad:

class BankAccount {
  balance: number = 0;
  // ...
}

const value = 100;
const account = new BankAccount();

if (value < 0) {
  throw new Error('Cannot set negative balance.');
}

account.balance = value;

Good:

class BankAccount {
  private accountBalance: number = 0;

  get balance(): number {
    return this.accountBalance;
  }

  set balance(value: number) {
    if (value < 0) {
      throw new Error('Cannot set negative balance.');
    }

    this.accountBalance = value;
  }

  // ...
}

const account = new BankAccount();
account.balance = 100;

⬆ back to top

Make objects have private/protected members

TypeScript supports public (default), protected and private accessors on class members.

Bad:

class Circle {
  radius: number;
  
  constructor(radius: number) {
    this.radius = radius;
  }

  perimeter(){
    return 2 * Math.PI * this.radius;
  }

  surface(){
    return Math.PI * this.radius * this.radius;
  }
}

Good:

class Circle {
  constructor(private readonly radius: number) {
  }

  perimeter(){
    return 2 * Math.PI * this.radius;
  }

  surface(){
    return Math.PI * this.radius * this.radius;
  }
}

⬆ back to top

Prefer readonly properties

TypeScript's type system allows you to mark individual properties on an interface / class as readonly. This allows you to work in a functional way (unexpected mutation is bad).
For more advanced scenarios there is a built-in type Readonly that takes a type T and marks all of its properties as readonly using mapped types (see mapped types).

Bad:

interface Config {
  host: string;
  port: string;
  db: string;
}

Good:

interface Config {
  readonly host: string;
  readonly port: string;
  readonly db: string;
}

Concurrency

Prefer promises vs callbacks

Callbacks aren't clean, and they cause excessive amounts of nesting (the callback hell).
There are utilities that transform existing functions using the callback style to a version that returns promises (for Node.js see util.promisify, for general purpose see pify, es6-promisify)

Bad:

import { get } from 'request';
import { writeFile } from 'fs';

function downloadPage(url: string, saveTo: string, callback: (error: Error, content?: string) => void){
  get(url, (error, response) => {
    if (error) {
      callback(error);
    } else {
      writeFile(saveTo, response.body, (error) => {
        if (error) {
          callback(error);
        } else {
          callback(null, response.body);
        }
      });
    }
  })
}

downloadPage('https://en.wikipedia.org/wiki/Robert_Cecil_Martin', 'article.html', (error, content) => {
  if (error) {
    console.error(error);
  } else {
    console.log(content);
  }
});

Promises supports a few patterns that could be useful in some cases:

Pattern	Description
Promise.resolve(value)	Convert a value into a resolved promise.
Promise.reject(error)	Convert an error into a rejected promise.
Promise.all(promises)	Returns a new promise which is fulfilled with an array of fulfillment values for the passed promises or rejects with the reason of the first promise that rejects.
Promise.race(promises)	Returns a new promise which is fulfilled/rejected with the result/error of the first settled promise from the array of passed promises.

Promise.all is especially useful when there is a need to run tasks in parallel. Promise.race makes it easier to implement things like timeouts for promises.

Good:

import { get } from 'request';
import { writeFile } from 'fs';
import { promisify } from 'util';

const write = promisify(writeFile);

function downloadPage(url: string, saveTo: string): Promise<string> {
  return get(url)
    .then(response => write(saveTo, response))
}

downloadPage('https://en.wikipedia.org/wiki/Robert_Cecil_Martin', 'article.html')
  .then(content => console.log(content))
  .catch(error => console.error(error));  

⬆ back to top

Async/Await are even cleaner than Promises

With async/await syntax you can write code that is far cleaner and more understandable that chained promises. Within a function prefixed with async keyword you have a way to tell the JavaScript runtime to pause the execution of code on the await keyword (when used on a promise).

Bad:

import { get } from 'request';
import { writeFile } from 'fs';
import { promisify } from 'util';

const write = util.promisify(writeFile);

function downloadPage(url: string, saveTo: string): Promise<string> {
  return get(url).then(response => write(saveTo, response))
}

downloadPage('https://en.wikipedia.org/wiki/Robert_Cecil_Martin', 'article.html')
  .then(content => console.log(content))
  .catch(error => console.error(error));  

Good:

import { get } from 'request';
import { writeFile } from 'fs';
import { promisify } from 'util';

const write = promisify(writeFile);

async function downloadPage(url: string, saveTo: string): Promise<string> {
  const response = await get(url);
  await write(saveTo, response);
  return response;
}

// somewhere in an async function
try {
  const content = await downloadPage('https://en.wikipedia.org/wiki/Robert_Cecil_Martin', 'article.html');
  console.log(content);
} catch (error) {
  console.error(error);
}

Comments

The use of a comments is an indication of failure to express without them. Code should be the only source of truth.

Don’t comment bad code—rewrite it.
— Brian W. Kernighan and P. J. Plaugher

Prefer self explanatory code instead of comments

Comments are an apology, not a requirement. Good code mostly documents itself.

Bad:

// Check if subscription is active.
if (subscription.endDate > Date.now) {  }

Good:

const isSubscriptionActive = subscription.endDate > Date.now;
if (isSubscriptionActive) { /* ... */ }

⬆ back to top

Don't leave commented out code in your codebase

Version control exists for a reason. Leave old code in your history.

Bad:

class User {
  name: string;
  email: string;
  // age: number;
  // jobPosition: string;
}

Good:

class User {
  name: string;
  email: string;
}

Don't have journal comments

Remember, use version control! There's no need for dead code, commented code, and especially journal comments. Use git log to get history!

Bad:

/**
 * 2016-12-20: Removed monads, didn't understand them (RM)
 * 2016-10-01: Improved using special monads (JP)
 * 2016-02-03: Added type-checking (LI)
 * 2015-03-14: Implemented combine (JR)
 */
function combine(a:number, b:number): number {
  return a + b;
}

Good:

function combine(a:number, b:number): number {
  return a + b;
}

⬆ back to top

Avoid positional markers

They usually just add noise. Let the functions and variable names along with the proper indentation and formatting give the visual structure to your code.
Optionally you can use IDE support for code folding (see Visual Studio Code folding regions).

Bad:

////////////////////////////////////////////////////////////////////////////////
// Client class
////////////////////////////////////////////////////////////////////////////////
class Client {
  id: number;
  name: string;
  address: Address;
  contact: Contact;

  ////////////////////////////////////////////////////////////////////////////////
  // public methods
  ////////////////////////////////////////////////////////////////////////////////
  public describe(): string {
    // ...
  }

  ////////////////////////////////////////////////////////////////////////////////
  // private methods
  ////////////////////////////////////////////////////////////////////////////////
  private describeAddress(): string {
    // ...
  }

  private describeContact(): string {
    // ...
  }
};

Good:

class Client {
  id: number;
  name: string;
  address: Address;
  contact: Contact;

  public describe(): string {
    // ...
  }

  private describeAddress(): string {
    // ...
  }

  private describeContact(): string {
    // ...
  }
};

⬆ back to top