Clean code for Typescript. Inspired by clean-code-javascript.

directory

  1. introduce
  2. variable
  3. function
  4. Objects and Data Structures
  5. Classes
  6. SOLID
  7. Testing
  8. Concurrency
  9. Error Handling
  10. Formatting
  11. Comments
  12. Translations

introduce

Principles of Software Engineering, from Robert C. Martin’s book Clean Code, for TypeScript. This is not a style guide; it is a guide to generating readable, reusable, and reconfigurable software in TypeScript.

Not every principle is strictly adhered to, and even fewer are universally agreed upon. These are guidelines, nothing more, but they are distilled from years of programming experience by the author of Clean Code.

Our software engineering skills are just over 50 years old and we still have a lot to learn. When software architecture is as old as the architecture itself, maybe then we have rules that are harder to follow. Now, let these guidelines serve as a litmus test for evaluating the quality of Typescript code that you and your team generate.

Beyond that: Knowing these rules doesn’t immediately make you a better software developer, and just because you’ve worked with them for years doesn’t mean you won’t make mistakes. Each piece of code begins as a first draft, like wet clay being molded into its final shape. Eventually, when we review with our friends, we chip away at imperfections. Don’t let these first drafts get in the way of improving your skills. Kill the code first!

Pass back to top

variable

Use meaningful variable names

Distinguish names in such a way that readers know exactly what their differences are.

Example:

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

Copy the code

Is:

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

Pass back to top

Use pronounceable variable names

If you can’t spell it, you have to declare it like an idiot.

Example:

type DtaRcrd102 = {
  genymdhms: Date;
  modymdhms: Date;
  pszqint: number;
}
Copy the code

Is:

type Customer = {
  generationTimestamp: Date;
  modificationTimestamp: Date;
  recordId: number;
}
Copy the code

Pass back to top

Use only one word for variables of the same type

Example:

function getUserInfo() :User;
function getUserDetails() :User;
function getUserData() :User;
Copy the code

Is:

function getUser() :User;
Copy the code

Pass back to top

Use searchable names

We often read more code than we write. It is therefore very important that the code we write be readable and searchable. By not naming variables that make sense and help understand the program, you do a disservice to the person reading the code. Make your name searchable. Tools like TSLint can help identify unnamed constants.

Example:

// What is 86400000?
setTimeout(restart, 86400000);
Copy the code

Is:

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

setTimeout(restart, MILLISECONDS_IN_A_DAY);
Copy the code

Pass back to top

Using variable expansion

Example:

declare const users: Map<string, User>;

for (const keyValue of users) {
  // Iterate over the user map
}
Copy the code

Is:

declare const users: Map<string, User>;

for (const [id, user] of users) {
  // Iterate over the user map
}
Copy the code

Pass back to top

Avoid tacit understanding

Explicit is better than implicit. Clarity is king.

Example:

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

Is:

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

Pass back to top

Do not add unnecessary context

Don’t repeat them in your variables if they are already specified in your class/type/object name.

Example:

type Car = {
  carMake: string;
  carModel: string;
  carColor: string;
}

function print(car: Car) :void {
  console.log(`${car.carMake} ${car.carModel} (${car.carColor}) `);
}
Copy the code

Is:

type Car = {
  make: string;
  model: string;
  color: string;
}

function print(car: Car) :void {
  console.log(`${car.make} ${car.model} (${car.color}) `);
}
Copy the code

Pass back to top

Use default parameters instead of short-circuit expressions or conditional statements

Default parameters are usually clearer than short-circuit expressions.

Example:

function loadPages(count? :number) {
  constloadCount = count ! = =undefined ? count : 10;
  // ...
}
Copy the code

Is:

function loadPages(count: number = 10) {
  // ...
}
Copy the code

Pass back to top