Clean code in TypeScript is code that is readable, testable, and maintainable — written so the next developer understands it without archaeology, and backed by a type system that makes invalid states unrepresentable. It matters because developers spend roughly 70 percent of their time reading code rather than writing it, so clarity pays for itself on every future change. The practice rests on a few pillars: expressive naming, small single-purpose functions, precise types instead of any, discriminated unions and utility types to model domains accurately, and the five SOLID principles — single responsibility, open/closed, Liskov substitution, interface segregation, and dependency inversion. Design patterns like Repository and Builder then give recurring problems recognizable shapes. This guide works through each of these with practical TypeScript examples, showing the before and after of code you will actually meet in real projects.
Any fool can write code that a computer can understand. Good programmers write code that humans can understand. — Martin Fowler
Why Does Clean Code Matter?
Developers spend approximately 70% of their time reading code. This makes readable code just as important as working code. Clean code reduces bugs, speeds up development, and makes onboarding new team members easier.
How Does TypeScript's Type System Help?
TypeScript's type system is your first line of defense against bugs and unclear code. Explicit types serve as documentation and catch errors at compile time.
// Bad - Type ambiguity
function process(data: any) {
return data.map(item => item.value);
}
// Good - Explicit type definitions
interface DataItem {
id: string;
value: number;
label: string;
}
function processData(data: DataItem[]): number[] {
return data.map(item => item.value);
}What Are the SOLID Principles in TypeScript?
Single Responsibility Principle (SRP)
Each class or function should have only one responsibility. When a class has multiple reasons to change, it becomes harder to maintain and test.
// Bad - Multiple responsibilities
class UserManager {
createUser(data: UserData) { /* ... */ }
sendEmail(user: User) { /* ... */ }
generateReport(users: User[]) { /* ... */ }
}
// Good - Separated responsibilities
class UserService {
constructor(private repository: UserRepository) {}
async createUser(data: UserData): Promise<User> {
return this.repository.create(data);
}
}
class EmailService {
async send(to: string, subject: string): Promise<void> {
// Email logic
}
}
class ReportGenerator {
generate(users: User[]): Report {
// Report logic
}
}Open/Closed Principle (OCP)
Classes should be open for extension but closed for modification. Use interfaces and inheritance to add new behavior without changing existing code.
interface PaymentProcessor {
process(amount: number): Promise<PaymentResult>;
}
class CreditCardProcessor implements PaymentProcessor {
async process(amount: number): Promise<PaymentResult> {
// Credit card logic
}
}
class PayPalProcessor implements PaymentProcessor {
async process(amount: number): Promise<PaymentResult> {
// PayPal logic
}
}
// Adding new payment method without modifying existing code
class CryptoProcessor implements PaymentProcessor {
async process(amount: number): Promise<PaymentResult> {
// Crypto logic
}
}Dependency Inversion Principle (DIP)
High-level modules should not depend on low-level modules. Both should depend on abstractions. This makes your code more testable and flexible.
// Repository interface (abstraction)
interface UserRepository {
findById(id: string): Promise<User | null>;
save(user: User): Promise<User>;
}
// Concrete implementation
class PostgresUserRepository implements UserRepository {
async findById(id: string): Promise<User | null> {
// PostgreSQL query
}
async save(user: User): Promise<User> {
// PostgreSQL insert
}
}
// Service depends on abstraction
class UserService {
constructor(private repository: UserRepository) {}
async getUser(id: string): Promise<User> {
const user = await this.repository.findById(id);
if (!user) throw new NotFoundError('User not found');
return user;
}
}Design Patterns
Factory Pattern
interface Notification {
send(message: string): void;
}
class NotificationFactory {
static create(type: 'email' | 'sms' | 'push'): Notification {
switch (type) {
case 'email': return new EmailNotification();
case 'sms': return new SMSNotification();
case 'push': return new PushNotification();
}
}
}
// Usage
const notification = NotificationFactory.create('email');
notification.send('Hello!');Practical Tips
Essential clean code practices:
- Use meaningful, descriptive variable and function names
- Keep functions short and focused on one task
- Use early returns to reduce nesting
- Prefer composition over inheritance
- Write self-documenting code over comments
- Use const by default, let only when necessary
Early Return Pattern
// Bad - Deeply nested
function getDiscount(user: User): number {
if (user.isActive) {
if (user.isPremium) {
if (user.yearsAsMember > 5) {
return 0.3;
}
return 0.2;
}
return 0.1;
}
return 0;
}
// Good - Early returns
function getDiscount(user: User): number {
if (!user.isActive) return 0;
if (!user.isPremium) return 0.1;
if (user.yearsAsMember <= 5) return 0.2;
return 0.3;
}Writing clean code is a habit that develops over time. TypeScript's strong type system and modern features make it easier to adopt these practices. Remember: code is written once but read hundreds of times.