Asher Cohen
Back to posts

Pillars of Clean Code

The fundamental principles that form the foundation of clean, maintainable code

Introduction

Clean code is built on time-tested principles that have proven their value across decades of software development. These pillars guide our decisions and help us write code that stands the test of time. When you master these fundamentals, you'll write code that's easier to read, test, modify, and maintain.

The Four Pillars

1. SOLID Principles

SOLID is an acronym for five design principles that help us create flexible, maintainable object-oriented code. These principles work together to reduce coupling, increase cohesion, and make your codebase more adaptable to change.

S — Single Responsibility Principle (SRP)

A class or function should have one, and only one, reason to change.

When a function does too much, it becomes harder to test, understand, and maintain. Violating SRP creates fragile code where changes cascade unexpectedly.

// ❌ Violates SRP - does too much
const processUser = (userData) => {
  // Validation
  if (!userData.email) throw new Error('Email required');
  
  // Database operation
  const user = db.save(userData);
  
  // Email notification
  sendWelcomeEmail(user.email);
  
  // Logging
  logger.log('User created', user);
  
  return user;
};

// ✅ Follows SRP - separated concerns
const validateUser = (userData) => { /* ... */ };
const saveUser = (userData) => { /* ... */ };
const sendWelcomeEmail = (email) => { /* ... */ };
const logUserCreation = (user) => { /* ... */ };

const processUser = (userData) => {
  validateUser(userData);
  const user = saveUser(userData);
  sendWelcomeEmail(user.email);
  logUserCreation(user);
  return user;
};

Benefits:

  • Easier to test each concern independently
  • Changes to one concern don't affect others
  • Clearer, more focused code
  • Better code reusability

O — Open-Closed Principle (OCP)

Entities should be open for extension but closed for modification.

You should be able to add new functionality without changing existing code. This prevents breaking changes and makes your code more stable.

// ❌ Violates OCP - must modify for new types
const calculateArea = (shape) => {
  if (shape.type === 'circle') {
    return Math.PI * shape.radius ** 2;
  } else if (shape.type === 'square') {
    return shape.side ** 2;
  }
  // Must add new if/else for each shape - violates OCP!
};

// ✅ Follows OCP - extend without modifying
const shapes = {
  circle: (r) => Math.PI * r ** 2,
  square: (s) => s ** 2,
  rectangle: (w, h) => w * h
};

const calculateArea = (shape) => shapes[shape.type](...shape.params);

// Add new shape without modifying existing code
shapes.triangle = (b, h) => 0.5 * b * h;

Benefits:

  • Stable, tested code remains unchanged
  • New features don't introduce bugs in existing features
  • Easier to extend functionality
  • Better for plugin architectures

L — Liskov Substitution Principle (LSP)

Objects of a superclass should be replaceable with objects of its subclasses.

In JavaScript, this means functions should work with any object that satisfies the expected interface. If a subclass breaks expected behavior, it violates LSP.

// ❌ Violates LSP - Bird can't fly
class Bird {
  fly() { /* ... */ }
}

class Penguin extends Bird {
  fly() {
    throw new Error("Penguins can't fly!");
  }
}

// Code expecting Bird to fly will break with Penguin

// ✅ Follows LSP - proper abstraction
class Bird {
  move() { /* ... */ }
}

class FlyingBird extends Bird {
  move() { this.fly(); }
  fly() { /* ... */ }
}

class Penguin extends Bird {
  move() { this.swim(); }
  swim() { /* ... */ }
}

Benefits:

  • Predictable behavior across subclasses
  • Safer polymorphism
  • Easier to reason about code
  • Prevents runtime errors from subtype substitution

I — Interface Segregation Principle (ISP)

Clients should not be forced to depend on interfaces they do not use.

Create specific interfaces rather than large, general-purpose ones. Large interfaces force implementations to provide methods they don't need.

// ❌ Violates ISP - forces unused methods
class Worker {
  work() { /* ... */ }
  eat() { /* ... */ }
  sleep() { /* ... */ }
}

class Robot implements Worker {
  work() { /* ... */ }
  eat() {
    throw new Error("Robots don't eat!");
  }
  sleep() {
    throw new Error("Robots don't sleep!");
  }
}

// ✅ Follows ISP - focused interfaces
class Workable {
  work() { /* ... */ }
}

class Feedable {
  eat() { /* ... */ }
}

class Sleepable {
  sleep() { /* ... */ }
}

class Human implements Workable, Feedable, Sleepable {
  work() { /* ... */ }
  eat() { /* ... */ }
  sleep() { /* ... */ }
}

class Robot implements Workable {
  work() { /* ... */ }
}

Benefits:

  • Classes only implement what they need
  • No dummy implementations or thrown errors
  • More flexible compositions
  • Easier to understand interface contracts

D — Dependency Inversion Principle (DIP)

Depend on abstractions, not on concrete implementations.

High-level modules should not depend on low-level modules. Both should depend on abstractions. This enables loose coupling and easier testing.

// ❌ Violates DIP - depends on concrete implementation
class UserService {
  constructor() {
    this.db = new MySQLDatabase();
  }
  
  getUser(id) {
    return this.db.query(`SELECT * FROM users WHERE id = ${id}`);
  }
}

// ✅ Follows DIP - depends on abstraction
class UserService {
  constructor(database) {
    this.db = database; // Any database implementing the interface
  }
  
  getUser(id) {
    return this.db.query(`SELECT * FROM users WHERE id = ${id}`);
  }
}

// Can now use any database
const userService = new UserService(new MySQLDatabase());
const userService = new UserService(new PostgreSQLDatabase());
const userService = new UserService(new MockDatabase()); // For testing!

Benefits:

  • Easy to swap implementations
  • Simplifies testing with mocks
  • Reduces coupling between layers
  • Enables dependency injection patterns

2. DRY (Don't Repeat Yourself)

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

Duplication is the enemy of maintainability. When you copy-paste code, you create multiple places that need to be updated when requirements change. This leads to bugs, inconsistencies, and technical debt.

Why DRY Matters

  • Easier Maintenance: Change logic in one place, not ten
  • Reduced Bugs: Fix a bug once, not in every duplicate
  • Clearer Intent: Single source of truth makes purpose obvious
  • Smaller Codebase: Less code to read, test, and understand
// ❌ Violates DRY - duplicate validation logic
const registerUser = (userData) => {
  if (!userData.email || !userData.email.includes('@')) {
    throw new Error('Invalid email');
  }
  // ...
};

const updateUser = (userId, userData) => {
  if (!userData.email || !userData.email.includes('@')) {
    throw new Error('Invalid email');
  }
  // ...
};

const resetPassword = (email) => {
  if (!email || !email.includes('@')) {
    throw new Error('Invalid email');
  }
  // ...
};

// ✅ Follows DRY - single validation function
const validateEmail = (email) => {
  if (!email || !email.includes('@')) {
    throw new Error('Invalid email');
  }
  return true;
};

const registerUser = (userData) => {
  validateEmail(userData.email);
  // ...
};

const updateUser = (userId, userData) => {
  validateEmail(userData.email);
  // ...
};

const resetPassword = (email) => {
  validateEmail(email);
  // ...
};

When to Apply DRY:

  • ✅ Same logic appears 2-3 times
  • ✅ Business rules used in multiple places
  • ✅ Utility functions needed across modules
  • ✅ Validation logic repeated across forms

When DRY Can Wait:

  • ⚠️ Accidental similarities (code looks similar but has different reasons to change)
  • ⚠️ Premature abstraction (wait until you see the pattern emerge)
  • ⚠️ Simple primitives (duplicating a string literal isn't always bad)

3. Separation of Concerns

Divide your program into distinct sections, each addressing a separate concern.

Separation of Concerns (SoC) is about organizing code so that each part has a clear, focused responsibility. This makes your codebase easier to understand, test, and modify.

The Three-Layer Architecture

A classic example of SoC is separating your application into three layers:

  1. Presentation Layer (UI): Handles user interface and interactions
  2. Business Logic Layer: Contains rules, calculations, and workflows
  3. Data Access Layer: Manages database operations and storage
// ❌ Violates SoC - mixing UI, business logic, and data access
class UserController {
  async handleRegistration(req, res) {
    // UI logic
    const email = req.body.email;
    const password = req.body.password;
    
    // Business logic
    if (password.length < 8) {
      return res.status(400).json({ error: 'Password too short' });
    }
    
    // Data access
    const user = await db.query(
      'INSERT INTO users (email, password) VALUES (?, ?)',
      [email, password]
    );
    
    // More business logic
    const token = jwt.sign({ userId: user.id }, 'secret');
    
    // More UI
    res.json({ token });
  }
}

// ✅ Follows SoC - clear separation
// Data Access Layer
class UserRepository {
  async create(email, password) {
    return await db.query(
      'INSERT INTO users (email, password) VALUES (?, ?)',
      [email, password]
    );
  }
}

// Business Logic Layer
class AuthService {
  constructor(userRepository) {
    this.userRepository = userRepository;
  }
  
  async register(email, password) {
    this.validatePassword(password);
    const user = await this.userRepository.create(email, password);
    return jwt.sign({ userId: user.id }, 'secret');
  }
  
  validatePassword(password) {
    if (password.length < 8) {
      throw new Error('Password too short');
    }
  }
}

// Presentation Layer
class UserController {
  constructor(authService) {
    this.authService = authService;
  }
  
  async handleRegistration(req, res) {
    try {
      const token = await this.authService.register(
        req.body.email,
        req.body.password
      );
      res.json({ token });
    } catch (error) {
      res.status(400).json({ error: error.message });
    }
  }
}

Benefits of Separation of Concerns:

  • Testability: Test each layer independently with mocks
  • Maintainability: Changes in one layer don't cascade
  • Reusability: Business logic can serve multiple UIs (web, mobile, API)
  • Parallel Development: Teams can work on different layers simultaneously
  • Clear Debugging: Easier to isolate where bugs originate

4. Low Coupling, High Cohesion

Low Coupling: Minimize dependencies between modules. Changes in one module shouldn't cascade through the system.

High Cohesion: Keep related functionality together. Modules should have a clear, focused purpose.

Understanding Coupling

Coupling measures how interconnected your modules are. High coupling creates a "spaghetti code" problem where changing one thing breaks everything.

// ❌ High Coupling - modules tightly interconnected
class Order {
  constructor() {
    this.payment = new Payment();
    this.inventory = new Inventory();
    this.email = new EmailService();
    this.shipping = new Shipping();
    this.logger = new Logger();
  }
  
  placeOrder(orderData) {
    this.payment.process(orderData.payment);
    this.inventory.reduce(orderData.items);
    this.email.sendConfirmation(orderData.email);
    this.shipping.schedule(orderData.address);
    this.logger.log('Order placed', orderData);
  }
}

// ✅ Low Coupling - modules connected via interfaces
class Order {
  constructor(paymentService, inventoryService, notificationService, shippingService) {
    this.paymentService = paymentService;
    this.inventoryService = inventoryService;
    this.notificationService = notificationService;
    this.shippingService = shippingService;
  }
  
  placeOrder(orderData) {
    this.paymentService.process(orderData.payment);
    this.inventoryService.reduce(orderData.items);
    this.notificationService.sendConfirmation(orderData.email);
    this.shippingService.schedule(orderData.address);
  }
}

Understanding Cohesion

Cohesion measures how closely related the responsibilities of a single module are. High cohesion means a module does one thing well.

// ❌ Low Cohesion - unrelated responsibilities in one module
class UserService {
  validateUser(userData) { /* ... */ }
  saveUser(userData) { /* ... */ }
  sendEmail(email) { /* ... */ }
  generateReport() { /* ... */ }
  calculateSalary(employeeId) { /* ... */ }
  connectDatabase() { /* ... */ }
}

// ✅ High Cohesion - focused, related responsibilities
class UserValidator {
  validate(userData) { /* ... */ }
  validateEmail(email) { /* ... */ }
  validatePassword(password) { /* ... */ }
}

class UserRepository {
  save(userData) { /* ... */ }
  findById(id) { /* ... */ }
  update(id, data) { /* ... */ }
}

class EmailService {
  sendWelcomeEmail(email) { /* ... */ }
  sendPasswordReset(email) { /* ... */ }
}

Benefits of Low Coupling, High Cohesion:

  • Easier Testing: Isolated modules are easier to test independently
  • Better Maintainability: Changes have localized impact
  • Improved Reusability: Cohesive modules can be reused in different contexts
  • Clearer Code: Purpose of each module is obvious
  • Parallel Development: Teams can work on different modules without conflicts

Applying These Principles

These pillars work together to create code that is:

  • Easy to Understand: Clear structure and responsibilities
  • Simple to Modify: Changes don't break unrelated parts
  • Resilient to Change: Adapts to new requirements gracefully
  • Pleasant to Work With: Developers enjoy maintaining it

Start Small

Don't try to apply all principles at once. Start with one:

  1. Week 1-2: Focus on Single Responsibility - break up large functions
  2. Week 3-4: Practice DRY - extract duplicate logic
  3. Week 5-6: Improve Separation of Concerns - organize into layers
  4. Week 7-8: Work on Coupling/Cohesion - refactor dependencies

Measure Progress

Ask yourself:

  • Can I explain what this function does in one sentence?
  • If I change this feature, how many files need to be modified?
  • Can I test this without mocking ten dependencies?
  • Would a new developer understand this code quickly?

Use TypeScript

TypeScript makes these principles easier to follow with interfaces, type safety, and better tooling support.

Test Your Code

Well-structured code is naturally easier to test. Use tests to verify you're on the right track.

Conclusion

Clean code is a practice, not a destination. These pillars guide you toward better code, but they're not rigid rules. Start with one principle, master it, then move to the next. Every refactoring makes your codebase better.

Remember: the goal is not perfect code, but code that works, is easy to understand, and can be changed safely when requirements evolve.

#clean-code #software-engineering #design-principles #solid #best-practices