System Design HLDRefactoring Toward Better Abstractions

Refactoring Toward Better Abstractions

LevelIntermediate

Duration90 mins

TopicRefactoring Toward Better Abstractions

2 / 4

Extracting Interfaces

The Interface as a Seam

Michael Feathers, in his seminal book Working Effectively with Legacy Code, introduced the concept of a seam—a place where you can alter behavior without editing the original code. Interfaces are the most powerful seams available in object-oriented programming. When you extract an interface, you're creating a point of flexibility where none existed before.

Interface extraction is often the first refactoring step toward better abstraction. It requires no behavioral changes to the existing code—you're simply declaring a contract that the existing implementation already satisfies. This makes it one of the safest refactorings you can perform, yet it opens enormous possibilities for extension, testing, and architectural evolution.

What You Will Learn

By the end of this page, you will master the mechanics of extracting interfaces from concrete classes, understand when interface extraction is the right choice versus other abstraction techniques, learn how to design stable, cohesive interfaces that last, and recognize the testing, decoupling, and extensibility benefits that interfaces provide.

The Mechanics of Interface Extraction

Interface extraction follows a predictable, safe pattern. Let's walk through the process step by step, understanding not just what to do but why each step matters.

Interface Extraction Steps

•Identify the Public Contract — Examine the concrete class and identify which public methods represent its essential capabilities. These methods form the interface. Private and protected methods are implementation details, not part of the contract.
•Determine the Conceptual Boundary — Not every public method belongs in the extracted interface. Include only methods that represent the abstraction you're creating. A ReportGenerator interface might not include setDebugMode() even if the concrete class has it.
•Create the Interface — Define the interface with the identified methods. Use clear, intention-revealing names. The interface name should describe what implementations DO, not what they ARE.
•Update the Concrete Class — Declare that the existing class implements the new interface. In most languages, this requires no code changes—just adding 'implements InterfaceName' to the class declaration.
•Update Dependent Code — Change code that uses the concrete class to depend on the interface instead. This is where the real decoupling happens.
•Verify Behavior Preservation — Run tests to confirm no behavior changed. This refactoring should be purely structural.

interface_extraction_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
52
53
// BEFORE: Concrete class with no interface
// All clients depend directly on this implementation
 
class PdfReportGenerator {
    private templateEngine: TemplateEngine;
    private fontManager: FontManager;
    
    constructor(templateEngine: TemplateEngine, fontManager: FontManager) {
        this.templateEngine = templateEngine;
        this.fontManager = fontManager;
    }
    
    // Public method - part of the conceptual contract
    generate(data: ReportData): Buffer {
        const html = this.templateEngine.render('pdf-template', data);
        return this.convertToPdf(html);
    }
    
    // Public method - part of the conceptual contract
    generateWithWatermark(data: ReportData, watermark: string): Buffer {
        const html = this.templateEngine.render('pdf-template', data);
        const pdf = this.convertToPdf(html);
        return this.addWatermark(pdf, watermark);
    }
    
    // Public but NOT part of the abstraction - debugging concern
    setDebugMode(enabled: boolean): void {
        this.templateEngine.setDebug(enabled);
    }
    
    // Private - implementation detail
    private convertToPdf(html: string): Buffer {
        // PDF conversion logic using fontManager
    }
    
    // Private - implementation detail  
    private addWatermark(pdf: Buffer, watermark: string): Buffer {
        // Watermark logic
    }
}
 
// Client code tightly coupled to PdfReportGenerator
class ReportService {
    private generator: PdfReportGenerator;  // Concrete dependency!
    
    constructor(generator: PdfReportGenerator) {
        this.generator = generator;
    }
    
    createMonthlyReport(data: SalesData): Buffer {
        return this.generator.generate(this.transformToReportData(data));
    }
}

What changed:

The concrete PdfReportGenerator is nearly untouched—only one line added
A new ReportGenerator interface declares the contract
ReportService depends on the interface, not the concrete class
New implementations can be added without modifying existing code
Testing is dramatically easier with mock implementations

This is the power of interface extraction: minimal code changes, maximum architectural flexibility.

Deciding What Belongs in the Interface

The most critical decision in interface extraction is what to include. Include too little, and the interface won't capture the abstraction. Include too much, and the interface becomes a leaky mirror of the implementation.

The ISP Guidance:

The Interface Segregation Principle tells us that clients should not be forced to depend on methods they don't use. This principle directly informs interface design:

Include in Interface

•Methods that define the core abstraction
•Operations all implementations must support
•Methods clients actually need to call
•Behaviors that vary across implementations
•The minimum contract for substitutability

Exclude from Interface

•Implementation-specific configuration
•Debugging or diagnostic methods
•Lifecycle methods specific to one impl
•Methods not used by interface clients
•Internal optimization hooks

interface_design_choices.ts
TypeScript
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
52
53
54
55
56
// EXAMPLE: Deciding interface contents for a notification service
 
class EmailNotificationService {
    private smtpClient: SmtpClient;
    private rateLimiter: RateLimiter;
    private templateCache: Map<string, Template>;
    
    // ✅ INCLUDE: Core behavior that defines "notification"
    send(recipient: string, message: NotificationMessage): Promise<void>;
    
    // ✅ INCLUDE: Batch operations - core capability
    sendBulk(notifications: Notification[]): Promise<BulkResult>;
    
    // ❌ EXCLUDE: Email-specific configuration
    setSmtpSettings(settings: SmtpSettings): void;
    
    // ❌ EXCLUDE: Implementation-specific caching
    preloadTemplates(templateIds: string[]): Promise<void>;
    clearTemplateCache(): void;
    
    // ❓ CONSIDER: Might be interface-worthy if all notifiers support it
    getDeliveryStatus(notificationId: string): Promise<DeliveryStatus>;
    
    // ❌ EXCLUDE: Debug/admin concern, not client behavior
    getMetrics(): NotificationMetrics;
    enableDebugLogging(enabled: boolean): void;
}
 
// RESULT: Clean, focused interface
 
interface NotificationService {
    send(recipient: string, message: NotificationMessage): Promise<void>;
    sendBulk(notifications: Notification[]): Promise<BulkResult>;
    getDeliveryStatus(notificationId: string): Promise<DeliveryStatus>;
}
 
// Now different channels can implement the same interface
class SmsNotificationService implements NotificationService {
    // Different implementation, same contract
    async send(recipient: string, message: NotificationMessage): Promise<void> {
        // SMS-specific logic
    }
    
    // SMS-specific methods NOT in interface
    setTwilioCredentials(credentials: TwilioConfig): void;
}
 
class PushNotificationService implements NotificationService {
    // Different implementation, same contract
    async send(recipient: string, message: NotificationMessage): Promise<void> {
        // Push notification logic
    }
    
    // Push-specific methods NOT in interface
    registerDevice(deviceToken: string, platform: Platform): void;
}

The Client Perspective Test

To determine what belongs in an interface, examine the code that USES the class. Which methods does the client code actually call? Include those. Which methods are only called during initialization, configuration, or debugging? Those likely don't belong in the core interface.

Naming Interfaces Effectively

Interface naming is an art that directly impacts code readability and design clarity. A well-named interface communicates the abstraction's purpose; a poorly-named interface obscures it.

The fundamental rule: Interface names should describe what implementations do, not what they are.

Interface Naming Patterns
Pattern	Example	When to Use
Capability (-able)	Comparable, Serializable, Drawable	Single capability or trait the implementor provides
Role (-er)	Reader, Writer, Handler, Processor	Active participant in an operation
Service	PaymentService, NotificationService	Business capability with multiple operations
Repository	UserRepository, OrderRepository	Data access abstraction (DDD pattern)
Strategy	PricingStrategy, ValidationStrategy	Interchangeable algorithm (Strategy pattern)
Factory	ConnectionFactory, SessionFactory	Object creation abstraction
Simple Noun	Logger, Cache, Scheduler	When the concept is universally understood

interface_naming_examples.ts
TypeScript
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
// ❌ POOR: Names describe what it IS, not what it DOES
interface IDatabase { }           // "I" prefix is controversial and uninformative
interface AbstractPaymentHandler { }  // "Abstract" is redundant for interfaces
interface DataObject { }          // Too vague
interface UserInterface { }       // Confusing with UI; describes structure, not behavior
interface BaseCacheImpl { }       // "Base" and "Impl" are implementation concepts
 
// ✅ GOOD: Names describe capabilities and purpose
interface Cacheable { }           // Something that can be cached
interface PaymentProcessor { }    // Processes payments (role-based)
interface UserRepository { }      // Data access for users (DDD pattern)
interface ConnectionFactory { }   // Creates connections (factory pattern)
interface MessagePublisher { }    // Publishes messages (role-based)
 
// ✅ GOOD: Names match domain language
interface DiscountPolicy { }      // Domain term, clear purpose
interface ShippingCalculator { }  // Calculates shipping (role-based)
interface InventoryChecker { }    // Checks inventory (role-based)
interface OrderValidator { }      // Validates orders (role-based)
 
// CONTEXT MATTERS: Same concept, different names by context
 
// In a web framework:
interface RequestHandler { }      // Handles HTTP requests
interface MiddlewareFunction { }  // Middleware concept from Express/Koa
 
// In a message queue system:
interface MessageHandler { }      // Handles queue messages  
interface MessageConsumer { }     // Consumes from a queue
 
// In a logging library:
interface Logger { }              // Simple, universally understood
interface LogSink { }             // Where logs are written (output destination)
 
// The key is matching the vocabulary of the domain/context

Naming Guidelines

•Avoid 'I' prefix — The debate is ongoing, but 'I' adds no information. A type's role as interface should be clear from context and usage, not naming convention.
•Avoid 'Impl' suffix for implementations — Instead, use descriptive names: PdfReportGenerator, RedisCache, SmtpEmailSender.
•Match domain vocabulary — If stakeholders say 'discount policy,' name it DiscountPolicy, not DiscountCalculationStrategy.
•Be specific enough — Processor is too vague; PaymentProcessor is clear.
•Consider implementors — Will it be obvious what implementing this interface means? Runnable is clear; Doable is not.

The Concrete Class Naming Question

When you extract an interface, the existing concrete class often has the 'good' name. Options: (1) Rename concrete to something descriptive like PostgresUserRepository and give interface the simple name UserRepository. (2) Keep concrete name and use a more abstract interface name. Choose based on which name clients will use most.

The Benefits Unlocked by Interfaces

Interface extraction is valuable precisely because of the capabilities it unlocks. Understanding these benefits helps you recognize when interface extraction is the right refactoring and helps justify the investment to stakeholders.

Key Benefits of Interface Extraction

•Testability — Interfaces enable mock implementations for isolated unit testing. You can test business logic without databases, networks, or file systems.
•Loose Coupling — Client code depends on abstractions, not concrete implementations. Changes to implementations don't require changes to clients.
•Substitutability — Multiple implementations can be swapped at runtime. A/B testing, feature flags, and gradual rollouts become architectural possibilities.
•Parallel Development — Teams can work independently once interfaces are agreed upon. Frontend and backend, or multiple backend services, can develop in parallel.
•Documentation — A well-designed interface documents the contract that implementations must fulfill. It's executable documentation.
•Future Extensibility — New implementations can be added without modifying existing code. The Open/Closed Principle in action.

interface_benefits_demonstrated.ts
TypeScript
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
// BENEFIT: Testability
// Without interface - hard to test, requires real database
class OrderService_Hard {
    private db: PostgresDatabase;  // Concrete dependency
    
    createOrder(items: Item[]): Order {
        // How do you test this without a real database?
        const order = new Order(items);
        this.db.insert('orders', order);  // Real DB call in tests!
        return order;
    }
}
 
// With interface - easy to test with mock
class OrderService {
    constructor(private orderRepository: OrderRepository) {}  // Interface
    
    createOrder(items: Item[]): Order {
        const order = new Order(items);
        this.orderRepository.save(order);
        return order;
    }
}
 
// Test with mock
class MockOrderRepository implements OrderRepository {
    savedOrders: Order[] = [];
    
    save(order: Order): void {
        this.savedOrders.push(order);
    }
}
 
test('createOrder saves to repository', () => {
    const mockRepo = new MockOrderRepository();
    const service = new OrderService(mockRepo);
    
    service.createOrder([{ id: '1', price: 10 }]);
    
    expect(mockRepo.savedOrders).toHaveLength(1);  // Easy assertion!
});
 
// BENEFIT: Substitutability - feature flags
class PaymentService {
    constructor(
        private paymentProcessor: PaymentProcessor,  // Interface
        private featureFlags: FeatureFlags
    ) {}
    
    processPayment(payment: Payment): PaymentResult {
        // Same interface, different implementations
        return this.paymentProcessor.process(payment);
    }
}
 
// Production instantiation with feature flag
const paymentProcessor = featureFlags.isEnabled('new-stripe-integration')
    ? new StripePaymentProcessor()    // New implementation
    : new LegacyPaymentProcessor();   // Old implementation
 
const paymentService = new PaymentService(paymentProcessor, featureFlags);
 
// BENEFIT: Parallel Development
// Team A: Works on interface and consumers
interface ReportExporter {
    export(report: Report, destination: Destination): Promise<ExportResult>;
}
 
// Team B: Implements interface independently
class S3ReportExporter implements ReportExporter {
    async export(report: Report, destination: Destination): Promise<ExportResult> {
        // Implementation can proceed independently
        // as long as it fulfills the interface contract
    }
}

The Investment Perspective

Interface extraction has upfront cost (creating the interface, updating dependencies) but pays ongoing dividends (easier testing, simpler changes, better extensibility). The payoff is proportional to: (1) how often the code changes, (2) how many clients depend on it, and (3) how likely alternative implementations are.

When NOT to Extract an Interface

Interfaces are powerful, but extracting them everywhere is a recipe for over-engineering. Knowing when not to extract is as important as knowing when to extract.

The core question: Will this interface ever have more than one real implementation? If the answer is 'probably not,' the interface may be unnecessary indirection.

Anti-Patterns: When to Skip Interface Extraction

•Single Implementation Forever — If you're 95% certain there will only ever be one implementation (utility class, framework integration, etc.), the interface adds indirection without benefit.
•Thin Wrappers — Creating an interface for a class that just wraps a library adds a layer of abstraction over an already-abstract layer. Consider whether you're truly decoupling or just adding ceremony.
•DTOs and Value Objects — Data Transfer Objects and simple value objects rarely need interfaces. They're data, not behavior. UserDto doesn't need an IUserDto interface.
•Internal Implementation Details — Classes that are implementation details of a larger abstraction don't need their own interfaces. The enclosing abstraction is the interface.
•Tight Deadline, No Clear Benefit — If extracting the interface won't help the current task and you're under time pressure, document the opportunity and defer.
•Premature Abstraction — You've identified only one concrete case so far. Wait for the second or third before abstracting.

unnecessary_interfaces.ts
TypeScript
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// ❌ UNNECESSARY: Interface for a utility class
// There will never be another implementation of "Math utilities"
interface IMathUtils {
    round(value: number, decimals: number): number;
    clamp(value: number, min: number, max: number): number;
}
 
class MathUtils implements IMathUtils {
    round(value: number, decimals: number): number { /* ... */ }
    clamp(value: number, min: number, max: number): number { /* ... */ }
}
 
// Just use the class directly - no interface needed
class MathUtils {
    static round(value: number, decimals: number): number { /* ... */ }
    static clamp(value: number, min: number, max: number): number { /* ... */ }
}
 
// ❌ UNNECESSARY: Interface for DTOs
interface IUserDto {
    id: string;
    name: string;
    email: string;
}
 
class UserDto implements IUserDto {
    constructor(
        public id: string,
        public name: string,
        public email: string
    ) {}
}
 
// Just use a simple type or class - no interface ceremony
type UserDto = {
    id: string;
    name: string;
    email: string;
};
 
// ❌ UNNECESSARY: Interface just to have an interface
// When there's zero chance of alternative implementations
interface IApplicationConfig {
    getDbConnectionString(): string;
    getLogLevel(): string;
}
 
class ApplicationConfig implements IApplicationConfig {
    getDbConnectionString(): string {
        return process.env.DB_CONNECTION!;
    }
}
 
// There will never be a MockApplicationConfig or TestApplicationConfig
// that provides different config values - just use the class
 
// ✅ EXCEPTION: Testing IS a valid "second implementation"
// If you need to mock config in tests, the interface becomes valuable
interface ConfigProvider {
    get(key: string): string;
}
 
class EnvironmentConfigProvider implements ConfigProvider {
    get(key: string): string { return process.env[key] || ''; }
}
 
class TestConfigProvider implements ConfigProvider {
    constructor(private values: Record<string, string>) {}
    get(key: string): string { return this.values[key] || ''; }
}

The Testing Exception

Testability is a legitimate reason for interface extraction even when you expect only one production implementation. If the class has dependencies that make testing difficult (databases, HTTP calls, file system), extracting an interface to enable mocking is valuable. The mock IS the second implementation.

Designing for Interface Stability

Once an interface is extracted and clients depend on it, changing the interface becomes costly—every implementation and every client must be updated. This is why interface stability is a critical design goal.

The stability challenge: You want interfaces to be stable (don't change often) but also useful (capture the right abstraction). These goals can conflict.

Principles for Stable Interfaces

•Minimize Surface Area — Include only essential methods. Every method in the interface is a promise you must maintain. Fewer methods = less change surface.
•Use Abstractions in Signatures — Method parameters and return types should themselves be abstractions when possible. process(Request): Response is more stable than process(HttpRequest): JsonBody.
•Favor Whole Objects Over Primitives — createUser(UserData): User is more stable than createUser(name, email, age, address): User. New fields are added to UserData without changing the interface.
•Design for Extension Points — If you anticipate certain kinds of change, design the interface to accommodate them. An options object is more extensible than positional parameters.
•Version When Breaking — When breaking changes are necessary, create a new version (PaymentProcessorV2) rather than changing the existing interface.
•Document Contracts Explicitly — Comments or documentation should specify preconditions, postconditions, and invariants. This makes implicit contracts explicit and reduces misunderstanding.

stable_interface_design.ts
TypeScript
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
52
53
54
55
56
57
58
59
60
61
62
63
// ❌ FRAGILE: Many parameters, each a change point
interface UserService {
    createUser(
        name: string,
        email: string,
        age: number,
        address: string,
        phoneNumber?: string,
        preferences?: UserPreferences
        // Adding more params = interface change!
    ): User;
}
 
// ✅ STABLE: Whole object parameter
interface UserService {
    createUser(userData: CreateUserRequest): User;
}
 
// New fields added to CreateUserRequest, not the interface
type CreateUserRequest = {
    name: string;
    email: string;
    age?: number;
    address?: string;
    phoneNumber?: string;
    // Adding more fields here is NOT an interface change
    loyaltyProgramId?: string;
    referralCode?: string;
};
 
// ❌ FRAGILE: Concrete types in signatures
interface DataExporter {
    exportToS3(data: PostgresQueryResult): S3Object;
    // Coupled to specific technologies!
}
 
// ✅ STABLE: Abstract types in signatures
interface DataExporter {
    export(data: ExportableData): ExportResult;
    // Works with any data source, any destination
}
 
// ❌ FRAGILE: Too many specific methods
interface ReportGenerator {
    generatePdfReport(data: ReportData): Buffer;
    generateHtmlReport(data: ReportData): Buffer;
    generateCsvReport(data: ReportData): Buffer;
    // Adding XML requires interface change!
}
 
// ✅ STABLE: Generic method with format parameter or separate interfaces
interface ReportGenerator {
    generate(data: ReportData, format: ReportFormat): Buffer;
}
 
// Or even better - format as a type parameter or separate implementations
interface ReportOutput {
    render(data: ReportData): Buffer;
}
 
class PdfReportOutput implements ReportOutput { }
class HtmlReportOutput implements ReportOutput { }
// New formats = new classes, not interface changes

The Stability Trade-off

Very stable interfaces may be less expressive or require more implementation effort. A generic export(data: ExportableData) is stable but puts more burden on implementations than exportToS3(data). Balance stability with usability based on how many implementations and clients you expect.

Interface Extraction Checklist

Let's consolidate the key considerations into a practical checklist you can use when extracting interfaces.

Pre-Extraction Questions

•Is there a genuine abstraction? — Do you have (or anticipate) multiple implementations? Would testing benefit from a mock?
•What is the abstraction? — Can you describe the concept in domain terms? What does 'implementing this interface' mean?
•Which methods belong? — What's the minimum set of methods that defines the contract? What should stay implementation-specific?
•What name captures the concept? — Does the name describe what implementations do, not what they are?
•Is the design stable? — Are you using abstractions in signatures? Will adding features require interface changes?

Post-Extraction Verification

•All tests still pass — Interface extraction should not change behavior
•Clients use the interface — Dependent code should depend on the interface, not the concrete class
•Interface is minimal — No unnecessary methods leaked from the implementation
•Interface is documented — Contracts, preconditions, and expected behaviors are clear
•Concrete class is clearly named — If the interface gets the 'good' name, ensure the implementation name is descriptive

What comes next:

Interface extraction is often just the beginning. In many cases, you'll find that multiple implementations share behavior—not just contracts. When this happens, you'll want to introduce an abstract class that provides the shared implementation while leaving variation points for subclasses.

The next page covers introducing abstract classes as a complementary technique to interface extraction.

Page Complete

You now understand how to extract interfaces systematically—determining what to include, naming effectively, understanding the benefits unlocked, recognizing when NOT to extract, and designing for stability. The next page covers introducing abstract classes for situations where shared implementation is needed alongside shared contracts.

2 / 4

Loading learning content...

System Design HLDRefactoring Toward Better Abstractions

Refactoring Toward Better Abstractions

LevelIntermediate

Duration90 mins

TopicRefactoring Toward Better Abstractions

2 / 4

Extracting Interfaces

The Interface as a Seam

What You Will Learn

The Mechanics of Interface Extraction

Interface extraction follows a predictable, safe pattern. Let's walk through the process step by step, understanding not just what to do but why each step matters.

Interface Extraction Steps

•Identify the Public Contract — Examine the concrete class and identify which public methods represent its essential capabilities. These methods form the interface. Private and protected methods are implementation details, not part of the contract.
•Determine the Conceptual Boundary — Not every public method belongs in the extracted interface. Include only methods that represent the abstraction you're creating. A ReportGenerator interface might not include setDebugMode() even if the concrete class has it.
•Create the Interface — Define the interface with the identified methods. Use clear, intention-revealing names. The interface name should describe what implementations DO, not what they ARE.
•Update the Concrete Class — Declare that the existing class implements the new interface. In most languages, this requires no code changes—just adding 'implements InterfaceName' to the class declaration.
•Update Dependent Code — Change code that uses the concrete class to depend on the interface instead. This is where the real decoupling happens.
•Verify Behavior Preservation — Run tests to confirm no behavior changed. This refactoring should be purely structural.

interface_extraction_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
52
53
// BEFORE: Concrete class with no interface
// All clients depend directly on this implementation
 
class PdfReportGenerator {
    private templateEngine: TemplateEngine;
    private fontManager: FontManager;
    
    constructor(templateEngine: TemplateEngine, fontManager: FontManager) {
        this.templateEngine = templateEngine;
        this.fontManager = fontManager;
    }
    
    // Public method - part of the conceptual contract
    generate(data: ReportData): Buffer {
        const html = this.templateEngine.render('pdf-template', data);
        return this.convertToPdf(html);
    }
    
    // Public method - part of the conceptual contract
    generateWithWatermark(data: ReportData, watermark: string): Buffer {
        const html = this.templateEngine.render('pdf-template', data);
        const pdf = this.convertToPdf(html);
        return this.addWatermark(pdf, watermark);
    }
    
    // Public but NOT part of the abstraction - debugging concern
    setDebugMode(enabled: boolean): void {
        this.templateEngine.setDebug(enabled);
    }
    
    // Private - implementation detail
    private convertToPdf(html: string): Buffer {
        // PDF conversion logic using fontManager
    }
    
    // Private - implementation detail  
    private addWatermark(pdf: Buffer, watermark: string): Buffer {
        // Watermark logic
    }
}
 
// Client code tightly coupled to PdfReportGenerator
class ReportService {
    private generator: PdfReportGenerator;  // Concrete dependency!
    
    constructor(generator: PdfReportGenerator) {
        this.generator = generator;
    }
    
    createMonthlyReport(data: SalesData): Buffer {
        return this.generator.generate(this.transformToReportData(data));
    }
}

What changed:

The concrete PdfReportGenerator is nearly untouched—only one line added
A new ReportGenerator interface declares the contract
ReportService depends on the interface, not the concrete class
New implementations can be added without modifying existing code
Testing is dramatically easier with mock implementations

This is the power of interface extraction: minimal code changes, maximum architectural flexibility.

Deciding What Belongs in the Interface

The ISP Guidance:

The Interface Segregation Principle tells us that clients should not be forced to depend on methods they don't use. This principle directly informs interface design:

Include in Interface

•Methods that define the core abstraction
•Operations all implementations must support
•Methods clients actually need to call
•Behaviors that vary across implementations
•The minimum contract for substitutability

Exclude from Interface

•Implementation-specific configuration
•Debugging or diagnostic methods
•Lifecycle methods specific to one impl
•Methods not used by interface clients
•Internal optimization hooks

interface_design_choices.ts
TypeScript
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
52
53
54
55
56
// EXAMPLE: Deciding interface contents for a notification service
 
class EmailNotificationService {
    private smtpClient: SmtpClient;
    private rateLimiter: RateLimiter;
    private templateCache: Map<string, Template>;
    
    // ✅ INCLUDE: Core behavior that defines "notification"
    send(recipient: string, message: NotificationMessage): Promise<void>;
    
    // ✅ INCLUDE: Batch operations - core capability
    sendBulk(notifications: Notification[]): Promise<BulkResult>;
    
    // ❌ EXCLUDE: Email-specific configuration
    setSmtpSettings(settings: SmtpSettings): void;
    
    // ❌ EXCLUDE: Implementation-specific caching
    preloadTemplates(templateIds: string[]): Promise<void>;
    clearTemplateCache(): void;
    
    // ❓ CONSIDER: Might be interface-worthy if all notifiers support it
    getDeliveryStatus(notificationId: string): Promise<DeliveryStatus>;
    
    // ❌ EXCLUDE: Debug/admin concern, not client behavior
    getMetrics(): NotificationMetrics;
    enableDebugLogging(enabled: boolean): void;
}
 
// RESULT: Clean, focused interface
 
interface NotificationService {
    send(recipient: string, message: NotificationMessage): Promise<void>;
    sendBulk(notifications: Notification[]): Promise<BulkResult>;
    getDeliveryStatus(notificationId: string): Promise<DeliveryStatus>;
}
 
// Now different channels can implement the same interface
class SmsNotificationService implements NotificationService {
    // Different implementation, same contract
    async send(recipient: string, message: NotificationMessage): Promise<void> {
        // SMS-specific logic
    }
    
    // SMS-specific methods NOT in interface
    setTwilioCredentials(credentials: TwilioConfig): void;
}
 
class PushNotificationService implements NotificationService {
    // Different implementation, same contract
    async send(recipient: string, message: NotificationMessage): Promise<void> {
        // Push notification logic
    }
    
    // Push-specific methods NOT in interface
    registerDevice(deviceToken: string, platform: Platform): void;
}

The Client Perspective Test

Naming Interfaces Effectively

Interface naming is an art that directly impacts code readability and design clarity. A well-named interface communicates the abstraction's purpose; a poorly-named interface obscures it.

The fundamental rule: Interface names should describe what implementations do, not what they are.

Interface Naming Patterns
Pattern	Example	When to Use
Capability (-able)	Comparable, Serializable, Drawable	Single capability or trait the implementor provides
Role (-er)	Reader, Writer, Handler, Processor	Active participant in an operation
Service	PaymentService, NotificationService	Business capability with multiple operations
Repository	UserRepository, OrderRepository	Data access abstraction (DDD pattern)
Strategy	PricingStrategy, ValidationStrategy	Interchangeable algorithm (Strategy pattern)
Factory	ConnectionFactory, SessionFactory	Object creation abstraction
Simple Noun	Logger, Cache, Scheduler	When the concept is universally understood

interface_naming_examples.ts
TypeScript
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
// ❌ POOR: Names describe what it IS, not what it DOES
interface IDatabase { }           // "I" prefix is controversial and uninformative
interface AbstractPaymentHandler { }  // "Abstract" is redundant for interfaces
interface DataObject { }          // Too vague
interface UserInterface { }       // Confusing with UI; describes structure, not behavior
interface BaseCacheImpl { }       // "Base" and "Impl" are implementation concepts
 
// ✅ GOOD: Names describe capabilities and purpose
interface Cacheable { }           // Something that can be cached
interface PaymentProcessor { }    // Processes payments (role-based)
interface UserRepository { }      // Data access for users (DDD pattern)
interface ConnectionFactory { }   // Creates connections (factory pattern)
interface MessagePublisher { }    // Publishes messages (role-based)
 
// ✅ GOOD: Names match domain language
interface DiscountPolicy { }      // Domain term, clear purpose
interface ShippingCalculator { }  // Calculates shipping (role-based)
interface InventoryChecker { }    // Checks inventory (role-based)
interface OrderValidator { }      // Validates orders (role-based)
 
// CONTEXT MATTERS: Same concept, different names by context
 
// In a web framework:
interface RequestHandler { }      // Handles HTTP requests
interface MiddlewareFunction { }  // Middleware concept from Express/Koa
 
// In a message queue system:
interface MessageHandler { }      // Handles queue messages  
interface MessageConsumer { }     // Consumes from a queue
 
// In a logging library:
interface Logger { }              // Simple, universally understood
interface LogSink { }             // Where logs are written (output destination)
 
// The key is matching the vocabulary of the domain/context

Naming Guidelines

•Avoid 'I' prefix — The debate is ongoing, but 'I' adds no information. A type's role as interface should be clear from context and usage, not naming convention.
•Avoid 'Impl' suffix for implementations — Instead, use descriptive names: PdfReportGenerator, RedisCache, SmtpEmailSender.
•Match domain vocabulary — If stakeholders say 'discount policy,' name it DiscountPolicy, not DiscountCalculationStrategy.
•Be specific enough — Processor is too vague; PaymentProcessor is clear.
•Consider implementors — Will it be obvious what implementing this interface means? Runnable is clear; Doable is not.

The Concrete Class Naming Question

The Benefits Unlocked by Interfaces

Key Benefits of Interface Extraction

•Testability — Interfaces enable mock implementations for isolated unit testing. You can test business logic without databases, networks, or file systems.
•Loose Coupling — Client code depends on abstractions, not concrete implementations. Changes to implementations don't require changes to clients.
•Substitutability — Multiple implementations can be swapped at runtime. A/B testing, feature flags, and gradual rollouts become architectural possibilities.
•Parallel Development — Teams can work independently once interfaces are agreed upon. Frontend and backend, or multiple backend services, can develop in parallel.
•Documentation — A well-designed interface documents the contract that implementations must fulfill. It's executable documentation.
•Future Extensibility — New implementations can be added without modifying existing code. The Open/Closed Principle in action.

interface_benefits_demonstrated.ts
TypeScript
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
// BENEFIT: Testability
// Without interface - hard to test, requires real database
class OrderService_Hard {
    private db: PostgresDatabase;  // Concrete dependency
    
    createOrder(items: Item[]): Order {
        // How do you test this without a real database?
        const order = new Order(items);
        this.db.insert('orders', order);  // Real DB call in tests!
        return order;
    }
}
 
// With interface - easy to test with mock
class OrderService {
    constructor(private orderRepository: OrderRepository) {}  // Interface
    
    createOrder(items: Item[]): Order {
        const order = new Order(items);
        this.orderRepository.save(order);
        return order;
    }
}
 
// Test with mock
class MockOrderRepository implements OrderRepository {
    savedOrders: Order[] = [];
    
    save(order: Order): void {
        this.savedOrders.push(order);
    }
}
 
test('createOrder saves to repository', () => {
    const mockRepo = new MockOrderRepository();
    const service = new OrderService(mockRepo);
    
    service.createOrder([{ id: '1', price: 10 }]);
    
    expect(mockRepo.savedOrders).toHaveLength(1);  // Easy assertion!
});
 
// BENEFIT: Substitutability - feature flags
class PaymentService {
    constructor(
        private paymentProcessor: PaymentProcessor,  // Interface
        private featureFlags: FeatureFlags
    ) {}
    
    processPayment(payment: Payment): PaymentResult {
        // Same interface, different implementations
        return this.paymentProcessor.process(payment);
    }
}
 
// Production instantiation with feature flag
const paymentProcessor = featureFlags.isEnabled('new-stripe-integration')
    ? new StripePaymentProcessor()    // New implementation
    : new LegacyPaymentProcessor();   // Old implementation
 
const paymentService = new PaymentService(paymentProcessor, featureFlags);
 
// BENEFIT: Parallel Development
// Team A: Works on interface and consumers
interface ReportExporter {
    export(report: Report, destination: Destination): Promise<ExportResult>;
}
 
// Team B: Implements interface independently
class S3ReportExporter implements ReportExporter {
    async export(report: Report, destination: Destination): Promise<ExportResult> {
        // Implementation can proceed independently
        // as long as it fulfills the interface contract
    }
}

The Investment Perspective

When NOT to Extract an Interface

Interfaces are powerful, but extracting them everywhere is a recipe for over-engineering. Knowing when not to extract is as important as knowing when to extract.

The core question: Will this interface ever have more than one real implementation? If the answer is 'probably not,' the interface may be unnecessary indirection.

Anti-Patterns: When to Skip Interface Extraction

•Single Implementation Forever — If you're 95% certain there will only ever be one implementation (utility class, framework integration, etc.), the interface adds indirection without benefit.
•Thin Wrappers — Creating an interface for a class that just wraps a library adds a layer of abstraction over an already-abstract layer. Consider whether you're truly decoupling or just adding ceremony.
•DTOs and Value Objects — Data Transfer Objects and simple value objects rarely need interfaces. They're data, not behavior. UserDto doesn't need an IUserDto interface.
•Internal Implementation Details — Classes that are implementation details of a larger abstraction don't need their own interfaces. The enclosing abstraction is the interface.
•Tight Deadline, No Clear Benefit — If extracting the interface won't help the current task and you're under time pressure, document the opportunity and defer.
•Premature Abstraction — You've identified only one concrete case so far. Wait for the second or third before abstracting.

unnecessary_interfaces.ts
TypeScript
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// ❌ UNNECESSARY: Interface for a utility class
// There will never be another implementation of "Math utilities"
interface IMathUtils {
    round(value: number, decimals: number): number;
    clamp(value: number, min: number, max: number): number;
}
 
class MathUtils implements IMathUtils {
    round(value: number, decimals: number): number { /* ... */ }
    clamp(value: number, min: number, max: number): number { /* ... */ }
}
 
// Just use the class directly - no interface needed
class MathUtils {
    static round(value: number, decimals: number): number { /* ... */ }
    static clamp(value: number, min: number, max: number): number { /* ... */ }
}
 
// ❌ UNNECESSARY: Interface for DTOs
interface IUserDto {
    id: string;
    name: string;
    email: string;
}
 
class UserDto implements IUserDto {
    constructor(
        public id: string,
        public name: string,
        public email: string
    ) {}
}
 
// Just use a simple type or class - no interface ceremony
type UserDto = {
    id: string;
    name: string;
    email: string;
};
 
// ❌ UNNECESSARY: Interface just to have an interface
// When there's zero chance of alternative implementations
interface IApplicationConfig {
    getDbConnectionString(): string;
    getLogLevel(): string;
}
 
class ApplicationConfig implements IApplicationConfig {
    getDbConnectionString(): string {
        return process.env.DB_CONNECTION!;
    }
}
 
// There will never be a MockApplicationConfig or TestApplicationConfig
// that provides different config values - just use the class
 
// ✅ EXCEPTION: Testing IS a valid "second implementation"
// If you need to mock config in tests, the interface becomes valuable
interface ConfigProvider {
    get(key: string): string;
}
 
class EnvironmentConfigProvider implements ConfigProvider {
    get(key: string): string { return process.env[key] || ''; }
}
 
class TestConfigProvider implements ConfigProvider {
    constructor(private values: Record<string, string>) {}
    get(key: string): string { return this.values[key] || ''; }
}

The Testing Exception

Designing for Interface Stability

The stability challenge: You want interfaces to be stable (don't change often) but also useful (capture the right abstraction). These goals can conflict.

Principles for Stable Interfaces

•Minimize Surface Area — Include only essential methods. Every method in the interface is a promise you must maintain. Fewer methods = less change surface.
•Use Abstractions in Signatures — Method parameters and return types should themselves be abstractions when possible. process(Request): Response is more stable than process(HttpRequest): JsonBody.
•Favor Whole Objects Over Primitives — createUser(UserData): User is more stable than createUser(name, email, age, address): User. New fields are added to UserData without changing the interface.
•Design for Extension Points — If you anticipate certain kinds of change, design the interface to accommodate them. An options object is more extensible than positional parameters.
•Version When Breaking — When breaking changes are necessary, create a new version (PaymentProcessorV2) rather than changing the existing interface.
•Document Contracts Explicitly — Comments or documentation should specify preconditions, postconditions, and invariants. This makes implicit contracts explicit and reduces misunderstanding.

stable_interface_design.ts
TypeScript
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
52
53
54
55
56
57
58
59
60
61
62
63
// ❌ FRAGILE: Many parameters, each a change point
interface UserService {
    createUser(
        name: string,
        email: string,
        age: number,
        address: string,
        phoneNumber?: string,
        preferences?: UserPreferences
        // Adding more params = interface change!
    ): User;
}
 
// ✅ STABLE: Whole object parameter
interface UserService {
    createUser(userData: CreateUserRequest): User;
}
 
// New fields added to CreateUserRequest, not the interface
type CreateUserRequest = {
    name: string;
    email: string;
    age?: number;
    address?: string;
    phoneNumber?: string;
    // Adding more fields here is NOT an interface change
    loyaltyProgramId?: string;
    referralCode?: string;
};
 
// ❌ FRAGILE: Concrete types in signatures
interface DataExporter {
    exportToS3(data: PostgresQueryResult): S3Object;
    // Coupled to specific technologies!
}
 
// ✅ STABLE: Abstract types in signatures
interface DataExporter {
    export(data: ExportableData): ExportResult;
    // Works with any data source, any destination
}
 
// ❌ FRAGILE: Too many specific methods
interface ReportGenerator {
    generatePdfReport(data: ReportData): Buffer;
    generateHtmlReport(data: ReportData): Buffer;
    generateCsvReport(data: ReportData): Buffer;
    // Adding XML requires interface change!
}
 
// ✅ STABLE: Generic method with format parameter or separate interfaces
interface ReportGenerator {
    generate(data: ReportData, format: ReportFormat): Buffer;
}
 
// Or even better - format as a type parameter or separate implementations
interface ReportOutput {
    render(data: ReportData): Buffer;
}
 
class PdfReportOutput implements ReportOutput { }
class HtmlReportOutput implements ReportOutput { }
// New formats = new classes, not interface changes

The Stability Trade-off

Interface Extraction Checklist

Let's consolidate the key considerations into a practical checklist you can use when extracting interfaces.

Pre-Extraction Questions

•Is there a genuine abstraction? — Do you have (or anticipate) multiple implementations? Would testing benefit from a mock?
•What is the abstraction? — Can you describe the concept in domain terms? What does 'implementing this interface' mean?
•Which methods belong? — What's the minimum set of methods that defines the contract? What should stay implementation-specific?
•What name captures the concept? — Does the name describe what implementations do, not what they are?
•Is the design stable? — Are you using abstractions in signatures? Will adding features require interface changes?

Post-Extraction Verification

•All tests still pass — Interface extraction should not change behavior
•Clients use the interface — Dependent code should depend on the interface, not the concrete class
•Interface is minimal — No unnecessary methods leaked from the implementation
•Interface is documented — Contracts, preconditions, and expected behaviors are clear
•Concrete class is clearly named — If the interface gets the 'good' name, ensure the implementation name is descriptive

What comes next:

The next page covers introducing abstract classes as a complementary technique to interface extraction.

Page Complete

2 / 4