Validating The Design - Learning Module

Loading content...

0/246

Simplicity Check

The Hardest Thing in Design: Knowing When to Stop

A paradox lies at the heart of software design: the skills that make you good at creating abstractions also tempt you to create unnecessary abstractions. The more design patterns you know, the more tempting it becomes to apply them whether needed or not. The more you've been burned by inflexible designs, the more you're inclined to over-engineer for flexibility.

Simplicity checking is the discipline that counterbalances this tendency. It asks not 'Is this design sophisticated?' but 'Is this design appropriately sophisticated?' Every element of complexity must justify its existence—and if it cannot, it must be removed.

What You Will Master

By the end of this page, you will understand how to identify unnecessary complexity, apply simplicity heuristics, distinguish essential from accidental complexity, and validate that your design achieves its goals with minimal moving parts.

The Philosophy of Simplicity

Simplicity is not the absence of features or capabilities. It is the absence of unnecessary complexity. A simple design accomplishes its goals with the minimum necessary machinery. It is easy to understand, easy to modify, and easy to debug.

Einstein's Maxim Applied to Software:

"Everything should be made as simple as possible, but no simpler."

This captures the essence: we seek optimal simplicity, not maximum simplicity. A design that is too simple will fail to meet requirements or will require extensive rework later. A design that is too complex wastes effort, introduces bugs, and slows future development.

Essential vs. Accidental Complexity:

Fred Brooks distinguished two types of complexity:

Essential Complexity: Inherent in the problem itself. A tax calculation system is complex because tax law is complex. This cannot be reduced without reducing functionality.
Accidental Complexity: Introduced by our solution, not required by the problem. Using six design patterns where two would suffice. Creating inheritance hierarchies for concepts that don't share behavior. Premature optimization that obscures intent.

Essential vs. Accidental Complexity
Type	Source	Can It Be Reduced?	Example
Essential	Problem domain	Only by reducing scope/requirements	Calculating compound interest requires the compound interest formula
Accidental	Our solution choices	Yes—better design choices	Factory-of-factories for objects created only once
Accidental	Tooling/framework limitations	Yes—better tools or workarounds	Boilerplate required by verbose frameworks
Accidental	Historical technical debt	Yes—refactoring and redesign	Legacy patterns maintained for compatibility

The Simplicity Goal

A well-designed system contains as much complexity as the problem requires and as little as the solution can tolerate. Simplicity checking targets accidental complexity—the complexity that we added unnecessarily and can remove.

Simplicity Metrics and Heuristics

While simplicity is somewhat subjective, we can apply objective heuristics and metrics during design validation:

Quantitative Metrics:

Simplicity Metrics
Metric	What It Measures	Warning Threshold	Action If Exceeded
Class Count	Number of classes in design	3x what seems minimum	Challenge each class's necessity
Abstraction Depth	Levels of inheritance/composition	4 levels	Flatten hierarchy where possible
Interface Count	Number of interfaces	Interfaces > 50% of classes	Audit for interfaces without variation
Method Count per Class	Average methods in a class	10 public methods	Split into focused classes
Parameter Count	Average parameters per method	4 parameters	Introduce parameter objects
Dependency Count	Average dependencies per class	5 injected dependencies	Challenge dependency necessity

Qualitative Heuristics:

The Simplicity Test Questions

•The Explanation Test: Can you explain this design to a competent developer in 10 minutes? If not, it may be too complex.
•The New Hire Test: Could a new team member understand and modify this design within their first week? If not, complexity is too high.
•The Deletion Test: For each element, can you articulate what would break if it were removed? If nothing would break, remove it.
•The Consolidation Test: Are there multiple elements that could be combined without loss of functionality or clarity?
•The Pattern Audit: For each design pattern used, can you explain why the simpler alternative was insufficient?
•The Layer Audit: Does data flow through the minimum number of layers necessary? Each layer adds complexity.

Complexity Smells: Warning Signs of Over-Engineering

Certain design patterns and structures are red flags that warrant scrutiny during simplicity checking:

Structural Complexity Smells

•Speculative Generality: Abstractions, parameters, or hooks for variations that don't exist and have no concrete plans to exist. 'We might need this someday' is not a justification.
•Unnecessary Indirection: Wrapper classes that add no value. Delegation that passes calls without transformation. Interfaces with single implementations and no planned variation.
•Parallel Inheritance Hierarchies: Every time you add a class to one hierarchy, you must add a corresponding class to another. This indicates a design that multiplies rather than encapsulates complexity.
•God Objects by Indirection: A class that delegates to many others but coordinates all their interactions. Complexity is distributed but not reduced.
•Dead Abstractions: Interfaces, abstract classes, or hooks that were created for extensibility but have never been extended and have no plans for extension.

Behavioral Complexity Smells

•Excessive Configuration: More configuration options than actual behavioral variations. Configuration becomes its own complex system.
•Ceremony Over Substance: More setup, registration, and wiring code than actual business logic. The scaffolding dwarfs the building.
•Callback Hell / Promise Chains: Deeply nested asynchronous code that flows through many callback layers. Consider simplifying the flow.
•Magic Values Everywhere: Behavior controlled by string constants, magic numbers, or convention-based naming that must be memorized.
•Multi-Step Simple Operations: Operations that should be simple (save an entity) require multiple coordinated calls across multiple classes.

❌ Speculative Generality:

// The only implementation we have or plan
interface IUserRepository {
    find(id: string): User | null;
}
 
// Unnecessary factory
interface IUserRepositoryFactory {
    create(): IUserRepository;
}
 
// Unnecessary abstract factory
interface IRepositoryFactoryFactory {
    createUserRepositoryFactory(): 
        IUserRepositoryFactory;
    createOrderRepositoryFactory(): 
        IOrderRepositoryFactory;
    // "We might need different DB someday"
}
 
// The actual code we need:
const user = repos.users.find(userId);
 
// What we have:
const factory = factoryFactory
    .createUserRepositoryFactory();
const repo = factory.create();
const user = repo.find(userId);
 
// 3 interfaces, 3 classes for one lookup

✅ Appropriate Simplicity:

// If we only have one implementation 
// and no concrete plans for others:
 
class UserRepository {
    constructor(private db: Database) {}
    
    find(id: string): User | null {
        return this.db.users.findUnique({
            where: { id }
        });
    }
    
    save(user: User): void {
        this.db.users.upsert({
            where: { id: user.id },
            update: user,
            create: user
        });
    }
}
 
// Simple injection, simple usage
class UserService {
    constructor(private userRepo: UserRepository) {}
    
    getUser(id: string): User | null {
        return this.userRepo.find(id);
    }
}
 
// If we later need interfaces for testing,
// TypeScript makes extraction trivial

The Abstraction Trap

Every abstraction has a cost: indirection, mental overhead, more files to navigate. Abstractions should exist because they provide value NOW, not because they might provide value someday. When in doubt, lean toward concreteness.

The Simplicity Validation Process

Apply this structured process during design validation to ensure appropriate simplicity:

Step 1: Element Justification Audit

For every major design element (class, interface, inheritance relationship, design pattern), answer: Why does this exist?

Acceptable answers:

'It implements a required feature.'
'It encapsulates a cohesive responsibility.'
'It enables a high-probability extension.'
'It significantly improves testability.'

Unacceptable answers:

'It follows the pattern we always use.'
'We might need it someday.'
'It's more object-oriented this way.'
'The book recommends it.'

Step 2: Layer Minimization Check

Examine the layers in your design. Common layers include:

Presentation (Controllers, Views)
Application Services
Domain Model
Infrastructure (Repositories, Gateways)

For each layer, ask:

Does this layer add meaningfully distinct responsibility?
Would combining it with an adjacent layer reduce clarity or increase coupling?
Is data transformed meaningfully as it passes through, or just forwarded?

Merge layers that don't add distinct value. A three-layer architecture is not inherently better than a two-layer architecture.

Step 3: Interface Necessity Audit

For every interface in the design:

How many implementations exist today?
How many implementations are planned?
Is the interface required for testing (mocking dependencies)?

Interfaces with one implementation and no planned variation are candidates for removal unless:

They're at module boundaries for decoupling
They're required for dependency injection testing
They're part of a public API that should be stable

Step 4: Pattern Justification

For every design pattern in use, document:

What problem does this pattern solve in our specific case?
What would the simpler alternative look like?
What specific benefit did the pattern provide over the simpler alternative?

If you cannot articulate the concrete benefit, consider removing the pattern.

Pattern Justification Examples

•Strategy Pattern: 'We have 5 pricing algorithms that share the same contract. Without the pattern, we'd have a 200-line switch statement that must be edited for every new algorithm.'
•Factory Method: 'Object creation involves significant setup logic and resource allocation. Centralizing it prevents duplication and ensures proper initialization.'
•Observer Pattern: 'Order placement triggers 7 side effects. Without observers, the OrderService would have 7 dependencies and multiple reasons to change.'

Simplicity Validation Checklist

Apply this comprehensive checklist during design validation:

Structural Simplicity

•Have you challenged every class? Could any two classes be merged without loss of clarity?
•Are inheritance hierarchies shallow (≤3 levels)? Could any inheritance be replaced with composition?
•Does every interface have multiple implementations or a clear testing need?
•Does every design pattern solve a specific problem in this design? Is the simpler alternative inadequate?
•Are there any dead abstractions—extension points that will never be extended?

Flow Simplicity

•Can you trace a typical request through the design in under a minute?
•Does data flow through the minimum necessary layers?
•Is there excessive ceremony (setup, registration, factory calls) for simple operations?
•Are method call chains short (≤3 levels of delegation)?

Conceptual Simplicity

•Can the design be explained to a new team member in 15 minutes?
•Do class names clearly convey purpose without requiring documentation?
•Are there any 'clever' solutions that a future maintainer would struggle with?
•Is the design's mental model aligned with the problem domain's mental model?

Configuration Simplicity

•Is configuration minimal and focused on genuine variation points?
•Are there reasonable defaults for most configuration values?
•Is dependency injection configuration simple and understandable?
•Can the system run with zero configuration for development purposes?

Simplification Techniques

When the simplicity check reveals unnecessary complexity, apply these techniques to simplify:

1. Inline Classes:

If a class just wraps another class without adding behavior, inline it. A UserRepositoryWrapper that calls UserRepository with no transformation adds only confusion.

2. Collapse Hierarchies:

If an inheritance hierarchy has abstract classes with no actual shared behavior, or subclasses that override everything, flatten it. Move variations to composition or simply distinct classes.

3. Remove Dead Abstractions:

Interfaces, abstract factories, event systems, and plugin architectures created for extension that never materialized should be removed. They can be added back if the need arises.

4. Merge Small Classes:

Classes with only 2-3 methods that are always used together can often be merged. The goal is cohesive modules, not maximum class count.

5. Prefer Composition to Inheritance:

Complex inheritance hierarchies are often simpler as composed behaviors. Replace 'is-a' with 'has-a' when the relationship is about capability rather than identity.

6. Use Direct Dependencies:

If a service locator or complex factory exists for dependencies that could be directly injected, simplify to direct constructor injection.

simplification-example.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
// BEFORE: Unnecessary complexity
interface IUserValidator {
    validate(user: User): ValidationResult;
}
 
interface IUserValidatorFactory {
    create(config: ValidatorConfig): IUserValidator;
}
 
class CompositeUserValidator implements IUserValidator {
    constructor(private validators: IUserValidator[]) {}
    validate(user: User): ValidationResult {
        return this.validators.map(v => v.validate(user)).combine();
    }
}
 
class EmailValidator implements IUserValidator { /* ... */ }
class PasswordValidator implements IUserValidator { /* ... */ }
class AgeValidator implements IUserValidator { /* ... */ }
 
// Usage requires factory, config, composition...
 
// AFTER: Appropriate simplicity for the actual need
class UserValidator {
    validate(user: User): ValidationResult {
        const errors: ValidationError[] = [];
        
        if (!this.isValidEmail(user.email)) {
            errors.push({ field: 'email', message: 'Invalid email format' });
        }
        if (!this.isStrongPassword(user.password)) {
            errors.push({ field: 'password', message: 'Password too weak' });
        }
        if (user.age < 13) {
            errors.push({ field: 'age', message: 'Must be at least 13' });
        }
        
        return errors.length === 0
            ? ValidationResult.success()
            : ValidationResult.failure(errors);
    }
    
    private isValidEmail(email: string): boolean { /* ... */ }
    private isStrongPassword(password: string): boolean { /* ... */ }
}
 
// Direct usage
const result = new UserValidator().validate(user);
 
// If we later need pluggable validators, we can refactor.
// For now, simple and clear.

Summary: Integrating Simplicity into Design Validation

Simplicity checking is not the enemy of good design—it is the completion of good design. A design that solves the problem but drowns in unnecessary complexity is not done. The final step of design validation is ensuring that every element earns its place.

Key Takeaways:

Simplicity Check Principles

•Target accidental complexity: Essential complexity cannot be reduced, but accidental complexity can and must be eliminated.
•Apply metrics with judgment: Quantitative metrics provide warning signs, but require qualitative evaluation.
•Watch for complexity smells: Speculative generality, unnecessary indirection, and dead abstractions indicate over-engineering.
•Justify every element: Every class, interface, and pattern must have a concrete reason for existence.
•Simplify proactively: Apply simplification techniques before implementation, when changes are cheap.

The Balance:

Design validation requires balancing multiple concerns:

Correctness: The design must solve the problem.
SOLID Compliance: The design must be well-structured.
Extensibility: The design must accommodate anticipated change.
Simplicity: The design must not exceed necessary complexity.

These concerns sometimes conflict. A simpler design might be less extensible. A more extensible design might be more complex. The skill of design is finding the balance point for each specific context.

Module Complete

You have completed the Validating the Design module. You now possess a comprehensive framework for design validation: a systematic checklist covering requirements alignment, structural integrity, behavioral correctness, operational readiness, and evolution capability; deep understanding of SOLID compliance evaluation; rigorous extensibility validation techniques; and the discipline of simplicity checking. These skills will serve you throughout your career, transforming you from a developer who creates designs to an engineer who validates them.