Clean Code Guide
About this guide
This guide provides practical knowledge for writing clean, maintainable code in TypeScript. It is not just a collection of rules: it is structured so you can understand step by step why each rule matters and how to apply it.
What is clean code
Clean code is code with the following characteristics:
- Easy to read (the intent is clear)
- Easy to understand (complexity is minimal)
- Easy to change (high maintainability)
- Easy to test (loosely coupled, highly cohesive)
- Fewer bugs (predictable behavior)
Why write clean code in TypeScript
TypeScript is a statically typed superset of JavaScript. The type system helps reduce bugs, but it cannot reach its full potential without good code design.
Chapter list
| # | Chapter | Overview |
|---|---|---|
| 01 | Naming conventions 1: case conventions, variables, and constants | Choosing among the four case conventions, and naming variables, booleans, and constants |
| 02 | Naming conventions 2: functions and classes | Naming functions with verb patterns, class name suffixes |
| 03 | Naming conventions 3: improving naming quality | Pronounceable names, consistent synonyms, criteria for abbreviations |
| 04 | Comments | Write the Why, let the code express the What |
| 05 | Defining variables | No magic numbers, prefer const, minimize scope |
| 06 | Defining functions | Single responsibility, pure functions, early returns |
| 07 | Loops | Choosing among forEach, map, filter, and reduce |
| 08 | Conditionals | Early returns, discriminated unions, polymorphism |
| 09 | Classes and interfaces | Single responsibility, encapsulation, composition |
| 10 | TypeScript-specific best practices | No any, leveraging unknown, generics |
| 11 | SOLID principles | The five principles with TypeScript examples |
| 12 | Summary | The big picture and a checklist |
A perspective: documenting your standards
This guide is a concrete set of standards for "writing cleanly in TypeScript," but if you are interested in the idea of documenting standards and building them into your workflow, also take a look at the blog post Introduction to Harness Engineering. It lays out a perspective on bundling rules / hooks / lint as a harness in the age of AI agents.
How the learning guides fit together
This guide focuses on best practices for design standards; it is a reference for people who can already write code and want to improve its quality. The type foundation is covered by the TypeScript Guide, and TypeScript Design Patterns carries on from there to widen your design options. For which guide covers which stage across the whole site, see the Introduction.
Going deeper on the five principles
Start with SOLID Principles in this guide for the definitions. Deep Dive into SOLID Principles then takes it further, across seven chapters written for intermediate and up. It asks why each principle exists, when breaking it is the right call, and how it gets misapplied. Every claim is traced back to the original sources, including how each principle is regarded today.