Designing for Abstraction - Learning Module

Loading content...

0/246

Hiding Implementation Details

The Art of Strategic Concealment

Once you've identified where abstraction boundaries should exist, the next challenge is ensuring those boundaries actually hide what they should hide. A boundary that leaks implementation details isn't really a boundary at all—it's a seam that creates coupling without providing benefits.

Information hiding is the foundational principle that makes abstraction work. It's not merely about making things private; it's about strategically deciding what knowledge should be local and what should be shared. Get this right, and your system becomes a collection of independently changeable components. Get it wrong, and changes ripple unpredictably through your codebase.

This page explores the techniques, patterns, and principles that enable effective information hiding—the craft of building abstractions that truly conceal rather than merely obscure.

What You Will Learn

By the end of this page, you will master the techniques for hiding implementation details behind clean interfaces. You'll understand what to hide, how to hide it effectively, and how to recognize when hiding has failed.

Parnas's Information Hiding Principle

In 1972, David Parnas published "On the Criteria To Be Used in Decomposing Systems into Modules"—a paper that fundamentally shaped how we think about software architecture. His central insight was revolutionary yet simple:

"Every module should hide a design decision from other modules."

Notice the word decision, not data. Information hiding isn't primarily about protecting fields from direct access—it's about shielding clients from design choices that might change.

Parnas identified that software systems fail to be maintainable not because of their size, but because changes propagate unexpectedly. When you change how data is stored, all code that knows about that storage format must also change. When you change an algorithm, all code that depends on that algorithm's behavior must adapt.

The Key Insight

The question isn't 'what data should be private?' but rather 'what design decisions are likely to change, and how can I hide them so that change is localized?' This reframes encapsulation from a mechanical practice to a strategic design activity.

What Constitutes a 'Design Decision'?

Design decisions that should be hidden include:

Decision Category	Examples	Why Hide It
Data Representation	Array vs linked list, JSON vs binary, SQL schema	Format changes shouldn't affect clients
Algorithm Choice	Sorting algorithm, search strategy, hashing function	Optimization shouldn't break dependents
External Dependencies	Which database, which API version, which library	Vendor changes shouldn't propagate
Hardware/Platform	File paths, endianness, thread model	Portability requires isolation
Policy/Configuration	Retry counts, timeout values, feature flags	Tuning shouldn't require code changes
Temporal Ordering	When initialization happens, caching strategy	Runtime behavior is implementation detail

Each of these decisions could change for legitimate reasons. Hiding them ensures that when they do change, only the hiding module needs to be modified.

design-decision-hiding.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
76
// ❌ EXPOSED DESIGN DECISIONS
// Every caller knows the implementation details
 
class UserStoreBad {
    // Design decision exposed: data is stored in a Map
    public users: Map<string, { name: string; email: string; createdAt: number }> = new Map();
    
    // Design decision exposed: timestamp is Unix milliseconds
    // Design decision exposed: object shape is known
    addUser(id: string, name: string, email: string) {
        this.users.set(id, { 
            name, 
            email, 
            createdAt: Date.now()  // Unix timestamp - exposed!
        });
    }
}
 
// Callers are coupled to ALL of these decisions:
const store = new UserStoreBad();
store.users.forEach((user, id) => {  // Knows it's a Map
    console.log(new Date(user.createdAt));  // Knows it's Unix ms
});
 
// ============================================================
 
// ✅ HIDDEN DESIGN DECISIONS
// Callers only know the interface, not the implementation
 
interface User {
    readonly id: UserId;
    readonly name: string;
    readonly email: Email;
    readonly createdAt: Date;
}
 
interface UserStore {
    add(name: string, email: Email): Promise<User>;
    findById(id: UserId): Promise<User | null>;
    findByEmail(email: Email): Promise<User | null>;
    list(options?: { limit?: number; offset?: number }): Promise<User[]>;
}
 
// Implementation hides ALL design decisions
class InMemoryUserStore implements UserStore {
    // Hidden: using Map
    private users = new Map<string, UserRecord>();
    
    // Hidden: internal record format differs from public User
    private toUser(record: UserRecord): User {
        return {
            id: new UserId(record.id),
            name: record.name,
            email: new Email(record.email),
            createdAt: new Date(record.createdAt),
        };
    }
    
    async add(name: string, email: Email): Promise<User> {
        const record: UserRecord = {
            id: crypto.randomUUID(),
            name,
            email: email.value,
            createdAt: Date.now(),  // Hidden: internal timestamp format
        };
        this.users.set(record.id, record);
        return this.toUser(record);
    }
    
    // ... other methods
}
 
// Callers are coupled ONLY to the interface:
const store: UserStore = new InMemoryUserStore();
const user = await store.add("Alice", new Email("alice@example.com"));
// ✅ Doesn't know about Map, timestamp format, or internal records

Levels of Hiding

Information hiding operates at multiple levels, each with its own techniques and considerations. Understanding these levels helps you apply the right hiding strategy for each situation.

Levels of Information Hiding

•Level 1: Data Hiding — The most basic level. Private fields, protected members. Prevents direct access to internal state but doesn't hide the fact that the state exists.
•Level 2: Structural Hiding — Hides how data is organized. Clients don't know if you're using arrays, trees, or graphs internally. They only see operations.
•Level 3: Algorithmic Hiding — Hides how operations are performed. Clients don't know the sorting algorithm, the search strategy, or the optimization techniques.
•Level 4: Representational Hiding — Hides how concepts are represented. Clients work with domain concepts; the module translates to/from internal representations.
•Level 5: Temporal Hiding — Hides when things happen. Clients don't know about caching, lazy initialization, prefetching, or batching.
•Level 6: Location Hiding — Hides where computation or storage occurs. Clients don't know if data is local, remote, in-memory, or on disk.

Illustrating the Levels

Consider a ProductCatalog service. At each level, different details are hidden:

Hiding Levels Applied to ProductCatalog
Level	What's Hidden	Interface Remains
Data	Product price is stored in cents (integer)	`getPrice()` returns Money object
Structural	Products stored in B-tree for range queries	`findInPriceRange(min, max)` returns products
Algorithmic	Uses binary search + bloom filter for search	`search(query)` returns matches
Representational	Internal JSON differs from domain Product	Client receives strongly-typed Product
Temporal	Products are cached, refreshed every 5 min	Client sees 'current' products
Location	Cold products in S3, hot products in Redis	Client doesn't know storage tiers

Start With the Interface

When designing a module, start by defining the interface—what clients need. Then work backward to implementation. This naturally leads to hiding at all levels, because you're not exposing implementation details; you're exposing capabilities.

Techniques for Effective Hiding

Hiding implementation details requires deliberate techniques. Simply marking fields as private isn't enough—you need to design interfaces that don't leak implementation concepts.

Interface Segregation means clients should only see the operations they need. This hides capabilities that aren't relevant to them.

Before: Fat interface exposing everything:

interface UserRepository {
    findById(id: UserId): User | null;
    findByEmail(email: Email): User | null;
    findAll(): User[];
    save(user: User): void;
    delete(id: UserId): void;
    // Admin methods mixed in
    purgeOldUsers(olderThan: Date): number;
    exportToCSV(): string;
    importFromCSV(data: string): void;
}

After: Segregated interfaces:

interface UserReader {
    findById(id: UserId): User | null;
    findByEmail(email: Email): User | null;
}

interface UserWriter {
    save(user: User): void;
    delete(id: UserId): void;
}

interface UserAdmin {
    purgeOldUsers(olderThan: Date): number;
    exportToCSV(): string;
    importFromCSV(data: string): void;
}

// Clients only see what they need
class UserService {
    constructor(private users: UserReader) {}
    // Cannot accidentally delete users—interface doesn't expose it
}

By segregating interfaces, each client is shielded from irrelevant operations. Changes to admin functions don't affect read-only clients.

The Principle of Minimal Interface

The Principle of Minimal Interface states: expose the smallest interface that fulfills client needs. Every additional public method, property, or type is a commitment you must maintain and a potential source of coupling.

This principle is about more than code minimalism—it's about semantic minimalism. A minimal interface is one where every exposed element is essential for clients to accomplish their goals.

Interface Bloat

•Exposing internal helper methods 'just in case'
•Making all fields public for 'flexibility'
•Returning internal collections directly
•Exposing implementation types in signatures
•Adding optional parameters that leak implementation

Minimal Interface

•Expose only what clients actually need
•Fields are private; provide methods if access is needed
•Return copies or immutable views of collections
•Use domain types, not implementation types
•Each method has a clear, singular purpose

The Iceberg Model

Think of a well-designed module as an iceberg. Above the water—visible to clients—is a small, clean, carefully designed interface. Below the water—hidden in the implementation—is the vast bulk of complexity, algorithms, data structures, and clever optimizations.

                    Visible (Public)
                    ───────────────
                        │ │ │
                      Interface
                    (tip of iceberg)
                        ─────
    ════════════════════════════════════════════════
                      /       \
                     /  Hidden  \
                    /  (Private)  \
                   / ─────────────── \
                  /  Implementation    \
                 /   Data Structures    \
                /    Algorithms          \
               /     Optimizations        \
              /      Helper Functions      \
             /       Configuration          \
            /─────────────────────────────────\

Questions to Ask:

Before making something public, ask:

Does any client actually need this?
Could I provide this capability differently?
Am I exposing an implementation detail?
Will I be able to change this later?
Does this increase or decrease the client's burden?

The Cost of Exposure

Every public method is a promise. Once clients depend on it, you can't change it without breaking them. The more you expose, the more you freeze. A bloated interface isn't a gift to your clients—it's a constraint on your own ability to improve the implementation.

Hiding and Contracts

Effective information hiding requires distinguishing between contract and implementation. The contract is what you promise to clients—it must be stable, documented, and reliable. The implementation is how you fulfill that promise—it can change freely.

Components of a Contract:

Aspect	Part of Contract?	Example
Method signature	✅ Yes	`findUser(id: UserId): User`
Return type	✅ Yes	Returns `User` object
Documented behavior	✅ Yes	"Returns null if not found"
Error conditions	✅ Yes	"Throws if id is invalid"
Preconditions	✅ Yes	"id must not be null"
Postconditions	✅ Yes	"Returned user has matching id"
Algorithm used	❌ No	Binary search vs. linear scan
Data structure	❌ No	HashMap vs. TreeMap
Database queries	❌ No	SQL implementation
Caching behavior	⚠️ Maybe	Depends on stated guarantees

The Contract Boundary

Performance guarantees are tricky. If you document 'O(1) lookup', that becomes part of your contract. Changing to O(n) would break clients even if the interface is unchanged. Be careful what you promise—implicit contracts are still contracts.

Documenting Contracts Explicitly

The best way to maintain the hiding boundary is to document contracts explicitly. This forces you to think carefully about what you're promising and makes the boundary between contract and implementation clear.

contract-documentation.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
/**
 * Repository for managing Order entities.
 * 
 * CONTRACT:
 * ---------
 * This interface defines the storage contract for Orders. Implementations
 * may use any storage mechanism but MUST satisfy these guarantees:
 * 
 * INVARIANTS:
 * - An Order's id is immutable after creation
 * - All Orders have unique ids within the system
 * - findById(save(order)) always returns an equivalent order
 * 
 * THREAD SAFETY:
 * - All operations are thread-safe
 * - No ordering guarantees between concurrent operations
 * 
 * IMPLEMENTATION NOTES (NOT part of contract):
 * - Current implementation uses PostgreSQL
 * - Uses read replicas for findById, writes to primary
 * - Caches recent orders for 30 seconds
 */
interface OrderRepository {
    /**
     * Retrieves an Order by its identifier.
     * 
     * @param id - The unique order identifier
     * @returns The Order if found, null otherwise
     * @throws InvalidOrderId if id is malformed
     * 
     * GUARANTEES:
     * - Returns null if no order exists with this id
     * - Returned order has the same id as requested
     * - Does not modify any state
     */
    findById(id: OrderId): Promise<Order | null>;
    
    /**
     * Persists an Order to storage.
     * 
     * @param order - The order to save
     * @throws DuplicateOrderError if order.id already exists
     * @throws InvalidOrderError if order fails validation
     * 
     * GUARANTEES:
     * - After successful return, order is durably stored
     * - If exception thrown, storage state is unchanged
     * - Order can be retrieved via findById after save
     */
    save(order: Order): Promise<void>;
}

Common Hiding Failures

Despite best intentions, implementation details often leak through interfaces. Understanding common failure modes helps you avoid them and recognize them in code reviews.

Common Hiding Failures

•Returning Mutable Internals — Returning internal collections or mutable objects allows clients to modify your state. Even if they don't intend to, they're now coupled to your internal structure.
•Implementation Types in Signatures — Using ArrayList instead of List, HashMap instead of Map, or ORM entities instead of domain objects exposes specific choices.
•Leaky Exceptions — Throwing SQLException from a repository exposes that you're using SQL. Wrap and translate exceptions at boundaries.
•Configuration in Interface — Methods like setBufferSize(int) expose internal optimization strategies. Prefer injection at construction or invisible auto-tuning.
•Order-Dependent Methods — If clients must call init() before process(), you've leaked your initialization strategy. Use constructor injection or lazy initialization.
•Resource Management Leaks — Requiring clients to call close() or manage transactions exposes resource lifecycle. Consider RAII patterns or automatic resource management.

Detailed Example: Returning Mutable Internals

mutable-internal-leak.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
// ❌ LEAKING MUTABLE INTERNALS
class ShoppingCart {
    private items: CartItem[] = [];
    
    // Returns the actual internal array!
    getItems(): CartItem[] {
        return this.items;  // Clients can mutate this
    }
}
 
// Client code breaks encapsulation:
const cart = new ShoppingCart();
cart.getItems().push(new CartItem("stolen", -1000));  // Adds directly!
cart.getItems().length = 0;  // Clears cart without going through API!
 
// ============================================================
 
// ✅ PROPER HIDING
class ShoppingCart {
    private items: CartItem[] = [];
    
    // Returns defensive copy
    getItems(): readonly CartItem[] {
        return [...this.items];  // New array, can't affect internal
    }
    
    // Or return an immutable view
    getItemsView(): ReadonlyArray<CartItem> {
        return Object.freeze([...this.items]);
    }
    
    // Better: don't expose items at all
    itemCount(): number {
        return this.items.length;
    }
    
    totalPrice(): Money {
        return this.items.reduce(
            (sum, item) => sum.add(item.price), 
            Money.zero()
        );
    }
    
    // Controlled mutation
    addItem(item: CartItem): void {
        this.validateItem(item);
        this.items.push(item);
    }
}

Rule of Three

For any value crossing a boundary, apply the Rule of Three: (1) Is it immutable? Good, return directly. (2) Is it primitive? Good, return directly. (3) Otherwise, return a copy or immutable view. This simple rule prevents most mutable internal leaks.

Testing the Hiding

How do you know if your hiding is effective? The ultimate test is whether you can change the implementation without affecting clients. But there are more immediate ways to validate your design:

Tests for Effective Hiding

•The Replacement Test — Can you replace the implementation with a completely different one (in-memory vs. database, sync vs. async) while keeping the interface identical? If not, your interface is leaking.
•The Mock Test — Can you create a test mock using only the public interface? If you need to access internals to write effective tests, the interface isn't sufficient.
•The Description Test — Can you describe what the module does without mentioning how? If you can't explain UserRepository without saying 'SQL' or 'MongoDB', you've failed.
•The Dependency Test — Remove an implementation dependency (database driver, HTTP library). Does the interface still compile? If not, the dependency is leaking.
•The Change Impact Test — Change an implementation detail (algorithm, data structure). How many files need to change? If more than one, the detail leaked.

The Replacement Test in Detail

This is the most powerful validation. If your abstraction truly hides implementation, you should be able to provide radically different implementations:

replacement-test.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
// The interface should support ALL of these implementations
// without any changes to clients
 
interface MessageQueue {
    send(message: Message): Promise<void>;
    receive(): AsyncIterable<Message>;
}
 
// Implementation 1: In-memory (testing)
class InMemoryQueue implements MessageQueue { /* ... */ }
 
// Implementation 2: Redis (development)
class RedisQueue implements MessageQueue { /* ... */ }
 
// Implementation 3: Kafka (production)
class KafkaQueue implements MessageQueue { /* ... */ }
 
// Implementation 4: SQS (cloud deployment)
class SQSQueue implements MessageQueue { /* ... */ }
 
// Client code works identically with all of them:
class NotificationService {
    constructor(private queue: MessageQueue) {}
    
    async notify(user: User, message: string): Promise<void> {
        await this.queue.send({
            to: user.email,
            body: message,
            timestamp: new Date(),
        });
    }
}
 
// Test: uses InMemoryQueue
// Dev: uses RedisQueue  
// Prod: uses KafkaQueue
// All work without any code changes to NotificationService

Summary: Hiding Implementation Details

Hiding implementation details is the mechanism that makes abstraction boundaries meaningful. Let's consolidate the key principles:

Key Takeaways

•Hide design decisions, not just data — Parnas taught us to hide what changes. Identify decisions likely to change and shield clients from them.
•Hiding operates at multiple levels — From data representation through algorithms to location. Consider what to hide at each level.
•Use deliberate techniques — Interface segregation, value objects, facades, and anti-corruption layers each serve specific hiding needs.
•Minimize your interface — Every public element is a constraint. Expose only what clients actually need.
•Distinguish contract from implementation — Document what you promise; change freely what you don't.
•Watch for common failures — Mutable internals, implementation types in signatures, and leaky exceptions break hiding.
•Test your hiding — Use the replacement test: can you swap implementations without client changes?

What's Next:

We've learned where to draw boundaries and how to hide implementation behind them. The next page explores the complementary challenge: how to design interfaces that remain stable while allowing implementations to be flexible. This is the art of creating extension points without over-engineering.

Page Complete

You now understand the techniques for effectively hiding implementation details behind clean interfaces. These skills enable you to create truly independent components that can evolve without breaking their clients.

Hiding Implementation Details

The Art of Strategic Concealment

This page explores the techniques, patterns, and principles that enable effective information hiding—the craft of building abstractions that truly conceal rather than merely obscure.

What You Will Learn

Parnas's Information Hiding Principle

"Every module should hide a design decision from other modules."

Notice the word decision, not data. Information hiding isn't primarily about protecting fields from direct access—it's about shielding clients from design choices that might change.

The Key Insight

What Constitutes a 'Design Decision'?

Design decisions that should be hidden include:

Decision Category	Examples	Why Hide It
Data Representation	Array vs linked list, JSON vs binary, SQL schema	Format changes shouldn't affect clients
Algorithm Choice	Sorting algorithm, search strategy, hashing function	Optimization shouldn't break dependents
External Dependencies	Which database, which API version, which library	Vendor changes shouldn't propagate
Hardware/Platform	File paths, endianness, thread model	Portability requires isolation
Policy/Configuration	Retry counts, timeout values, feature flags	Tuning shouldn't require code changes
Temporal Ordering	When initialization happens, caching strategy	Runtime behavior is implementation detail

Each of these decisions could change for legitimate reasons. Hiding them ensures that when they do change, only the hiding module needs to be modified.

design-decision-hiding.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
76
// ❌ EXPOSED DESIGN DECISIONS
// Every caller knows the implementation details
 
class UserStoreBad {
    // Design decision exposed: data is stored in a Map
    public users: Map<string, { name: string; email: string; createdAt: number }> = new Map();
    
    // Design decision exposed: timestamp is Unix milliseconds
    // Design decision exposed: object shape is known
    addUser(id: string, name: string, email: string) {
        this.users.set(id, { 
            name, 
            email, 
            createdAt: Date.now()  // Unix timestamp - exposed!
        });
    }
}
 
// Callers are coupled to ALL of these decisions:
const store = new UserStoreBad();
store.users.forEach((user, id) => {  // Knows it's a Map
    console.log(new Date(user.createdAt));  // Knows it's Unix ms
});
 
// ============================================================
 
// ✅ HIDDEN DESIGN DECISIONS
// Callers only know the interface, not the implementation
 
interface User {
    readonly id: UserId;
    readonly name: string;
    readonly email: Email;
    readonly createdAt: Date;
}
 
interface UserStore {
    add(name: string, email: Email): Promise<User>;
    findById(id: UserId): Promise<User | null>;
    findByEmail(email: Email): Promise<User | null>;
    list(options?: { limit?: number; offset?: number }): Promise<User[]>;
}
 
// Implementation hides ALL design decisions
class InMemoryUserStore implements UserStore {
    // Hidden: using Map
    private users = new Map<string, UserRecord>();
    
    // Hidden: internal record format differs from public User
    private toUser(record: UserRecord): User {
        return {
            id: new UserId(record.id),
            name: record.name,
            email: new Email(record.email),
            createdAt: new Date(record.createdAt),
        };
    }
    
    async add(name: string, email: Email): Promise<User> {
        const record: UserRecord = {
            id: crypto.randomUUID(),
            name,
            email: email.value,
            createdAt: Date.now(),  // Hidden: internal timestamp format
        };
        this.users.set(record.id, record);
        return this.toUser(record);
    }
    
    // ... other methods
}
 
// Callers are coupled ONLY to the interface:
const store: UserStore = new InMemoryUserStore();
const user = await store.add("Alice", new Email("alice@example.com"));
// ✅ Doesn't know about Map, timestamp format, or internal records

Levels of Hiding

Information hiding operates at multiple levels, each with its own techniques and considerations. Understanding these levels helps you apply the right hiding strategy for each situation.

Levels of Information Hiding

•Level 1: Data Hiding — The most basic level. Private fields, protected members. Prevents direct access to internal state but doesn't hide the fact that the state exists.
•Level 2: Structural Hiding — Hides how data is organized. Clients don't know if you're using arrays, trees, or graphs internally. They only see operations.
•Level 3: Algorithmic Hiding — Hides how operations are performed. Clients don't know the sorting algorithm, the search strategy, or the optimization techniques.
•Level 4: Representational Hiding — Hides how concepts are represented. Clients work with domain concepts; the module translates to/from internal representations.
•Level 5: Temporal Hiding — Hides when things happen. Clients don't know about caching, lazy initialization, prefetching, or batching.
•Level 6: Location Hiding — Hides where computation or storage occurs. Clients don't know if data is local, remote, in-memory, or on disk.

Illustrating the Levels

Consider a ProductCatalog service. At each level, different details are hidden:

Hiding Levels Applied to ProductCatalog
Level	What's Hidden	Interface Remains
Data	Product price is stored in cents (integer)	`getPrice()` returns Money object
Structural	Products stored in B-tree for range queries	`findInPriceRange(min, max)` returns products
Algorithmic	Uses binary search + bloom filter for search	`search(query)` returns matches
Representational	Internal JSON differs from domain Product	Client receives strongly-typed Product
Temporal	Products are cached, refreshed every 5 min	Client sees 'current' products
Location	Cold products in S3, hot products in Redis	Client doesn't know storage tiers

Start With the Interface

Techniques for Effective Hiding

Hiding implementation details requires deliberate techniques. Simply marking fields as private isn't enough—you need to design interfaces that don't leak implementation concepts.

Interface Segregation means clients should only see the operations they need. This hides capabilities that aren't relevant to them.

Before: Fat interface exposing everything:

interface UserRepository {
    findById(id: UserId): User | null;
    findByEmail(email: Email): User | null;
    findAll(): User[];
    save(user: User): void;
    delete(id: UserId): void;
    // Admin methods mixed in
    purgeOldUsers(olderThan: Date): number;
    exportToCSV(): string;
    importFromCSV(data: string): void;
}

After: Segregated interfaces:

interface UserReader {
    findById(id: UserId): User | null;
    findByEmail(email: Email): User | null;
}

interface UserWriter {
    save(user: User): void;
    delete(id: UserId): void;
}

interface UserAdmin {
    purgeOldUsers(olderThan: Date): number;
    exportToCSV(): string;
    importFromCSV(data: string): void;
}

// Clients only see what they need
class UserService {
    constructor(private users: UserReader) {}
    // Cannot accidentally delete users—interface doesn't expose it
}

By segregating interfaces, each client is shielded from irrelevant operations. Changes to admin functions don't affect read-only clients.

The Principle of Minimal Interface

This principle is about more than code minimalism—it's about semantic minimalism. A minimal interface is one where every exposed element is essential for clients to accomplish their goals.

Interface Bloat

•Exposing internal helper methods 'just in case'
•Making all fields public for 'flexibility'
•Returning internal collections directly
•Exposing implementation types in signatures
•Adding optional parameters that leak implementation

Minimal Interface

•Expose only what clients actually need
•Fields are private; provide methods if access is needed
•Return copies or immutable views of collections
•Use domain types, not implementation types
•Each method has a clear, singular purpose

The Iceberg Model

                    Visible (Public)
                    ───────────────
                        │ │ │
                      Interface
                    (tip of iceberg)
                        ─────
    ════════════════════════════════════════════════
                      /       \
                     /  Hidden  \
                    /  (Private)  \
                   / ─────────────── \
                  /  Implementation    \
                 /   Data Structures    \
                /    Algorithms          \
               /     Optimizations        \
              /      Helper Functions      \
             /       Configuration          \
            /─────────────────────────────────\

Questions to Ask:

Before making something public, ask:

Does any client actually need this?
Could I provide this capability differently?
Am I exposing an implementation detail?
Will I be able to change this later?
Does this increase or decrease the client's burden?

The Cost of Exposure

Hiding and Contracts

Components of a Contract:

Aspect	Part of Contract?	Example
Method signature	✅ Yes	`findUser(id: UserId): User`
Return type	✅ Yes	Returns `User` object
Documented behavior	✅ Yes	"Returns null if not found"
Error conditions	✅ Yes	"Throws if id is invalid"
Preconditions	✅ Yes	"id must not be null"
Postconditions	✅ Yes	"Returned user has matching id"
Algorithm used	❌ No	Binary search vs. linear scan
Data structure	❌ No	HashMap vs. TreeMap
Database queries	❌ No	SQL implementation
Caching behavior	⚠️ Maybe	Depends on stated guarantees

The Contract Boundary

Documenting Contracts Explicitly

contract-documentation.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
/**
 * Repository for managing Order entities.
 * 
 * CONTRACT:
 * ---------
 * This interface defines the storage contract for Orders. Implementations
 * may use any storage mechanism but MUST satisfy these guarantees:
 * 
 * INVARIANTS:
 * - An Order's id is immutable after creation
 * - All Orders have unique ids within the system
 * - findById(save(order)) always returns an equivalent order
 * 
 * THREAD SAFETY:
 * - All operations are thread-safe
 * - No ordering guarantees between concurrent operations
 * 
 * IMPLEMENTATION NOTES (NOT part of contract):
 * - Current implementation uses PostgreSQL
 * - Uses read replicas for findById, writes to primary
 * - Caches recent orders for 30 seconds
 */
interface OrderRepository {
    /**
     * Retrieves an Order by its identifier.
     * 
     * @param id - The unique order identifier
     * @returns The Order if found, null otherwise
     * @throws InvalidOrderId if id is malformed
     * 
     * GUARANTEES:
     * - Returns null if no order exists with this id
     * - Returned order has the same id as requested
     * - Does not modify any state
     */
    findById(id: OrderId): Promise<Order | null>;
    
    /**
     * Persists an Order to storage.
     * 
     * @param order - The order to save
     * @throws DuplicateOrderError if order.id already exists
     * @throws InvalidOrderError if order fails validation
     * 
     * GUARANTEES:
     * - After successful return, order is durably stored
     * - If exception thrown, storage state is unchanged
     * - Order can be retrieved via findById after save
     */
    save(order: Order): Promise<void>;
}

Common Hiding Failures

Despite best intentions, implementation details often leak through interfaces. Understanding common failure modes helps you avoid them and recognize them in code reviews.

Common Hiding Failures

•Returning Mutable Internals — Returning internal collections or mutable objects allows clients to modify your state. Even if they don't intend to, they're now coupled to your internal structure.
•Implementation Types in Signatures — Using ArrayList instead of List, HashMap instead of Map, or ORM entities instead of domain objects exposes specific choices.
•Leaky Exceptions — Throwing SQLException from a repository exposes that you're using SQL. Wrap and translate exceptions at boundaries.
•Configuration in Interface — Methods like setBufferSize(int) expose internal optimization strategies. Prefer injection at construction or invisible auto-tuning.
•Order-Dependent Methods — If clients must call init() before process(), you've leaked your initialization strategy. Use constructor injection or lazy initialization.
•Resource Management Leaks — Requiring clients to call close() or manage transactions exposes resource lifecycle. Consider RAII patterns or automatic resource management.

Detailed Example: Returning Mutable Internals

mutable-internal-leak.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
// ❌ LEAKING MUTABLE INTERNALS
class ShoppingCart {
    private items: CartItem[] = [];
    
    // Returns the actual internal array!
    getItems(): CartItem[] {
        return this.items;  // Clients can mutate this
    }
}
 
// Client code breaks encapsulation:
const cart = new ShoppingCart();
cart.getItems().push(new CartItem("stolen", -1000));  // Adds directly!
cart.getItems().length = 0;  // Clears cart without going through API!
 
// ============================================================
 
// ✅ PROPER HIDING
class ShoppingCart {
    private items: CartItem[] = [];
    
    // Returns defensive copy
    getItems(): readonly CartItem[] {
        return [...this.items];  // New array, can't affect internal
    }
    
    // Or return an immutable view
    getItemsView(): ReadonlyArray<CartItem> {
        return Object.freeze([...this.items]);
    }
    
    // Better: don't expose items at all
    itemCount(): number {
        return this.items.length;
    }
    
    totalPrice(): Money {
        return this.items.reduce(
            (sum, item) => sum.add(item.price), 
            Money.zero()
        );
    }
    
    // Controlled mutation
    addItem(item: CartItem): void {
        this.validateItem(item);
        this.items.push(item);
    }
}

Rule of Three

Testing the Hiding

How do you know if your hiding is effective? The ultimate test is whether you can change the implementation without affecting clients. But there are more immediate ways to validate your design:

Tests for Effective Hiding

•The Replacement Test — Can you replace the implementation with a completely different one (in-memory vs. database, sync vs. async) while keeping the interface identical? If not, your interface is leaking.
•The Mock Test — Can you create a test mock using only the public interface? If you need to access internals to write effective tests, the interface isn't sufficient.
•The Description Test — Can you describe what the module does without mentioning how? If you can't explain UserRepository without saying 'SQL' or 'MongoDB', you've failed.
•The Dependency Test — Remove an implementation dependency (database driver, HTTP library). Does the interface still compile? If not, the dependency is leaking.
•The Change Impact Test — Change an implementation detail (algorithm, data structure). How many files need to change? If more than one, the detail leaked.

The Replacement Test in Detail

This is the most powerful validation. If your abstraction truly hides implementation, you should be able to provide radically different implementations:

replacement-test.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
// The interface should support ALL of these implementations
// without any changes to clients
 
interface MessageQueue {
    send(message: Message): Promise<void>;
    receive(): AsyncIterable<Message>;
}
 
// Implementation 1: In-memory (testing)
class InMemoryQueue implements MessageQueue { /* ... */ }
 
// Implementation 2: Redis (development)
class RedisQueue implements MessageQueue { /* ... */ }
 
// Implementation 3: Kafka (production)
class KafkaQueue implements MessageQueue { /* ... */ }
 
// Implementation 4: SQS (cloud deployment)
class SQSQueue implements MessageQueue { /* ... */ }
 
// Client code works identically with all of them:
class NotificationService {
    constructor(private queue: MessageQueue) {}
    
    async notify(user: User, message: string): Promise<void> {
        await this.queue.send({
            to: user.email,
            body: message,
            timestamp: new Date(),
        });
    }
}
 
// Test: uses InMemoryQueue
// Dev: uses RedisQueue  
// Prod: uses KafkaQueue
// All work without any code changes to NotificationService

Summary: Hiding Implementation Details

Hiding implementation details is the mechanism that makes abstraction boundaries meaningful. Let's consolidate the key principles:

Key Takeaways

•Hide design decisions, not just data — Parnas taught us to hide what changes. Identify decisions likely to change and shield clients from them.
•Hiding operates at multiple levels — From data representation through algorithms to location. Consider what to hide at each level.
•Use deliberate techniques — Interface segregation, value objects, facades, and anti-corruption layers each serve specific hiding needs.
•Minimize your interface — Every public element is a constraint. Expose only what clients actually need.
•Distinguish contract from implementation — Document what you promise; change freely what you don't.
•Watch for common failures — Mutable internals, implementation types in signatures, and leaky exceptions break hiding.
•Test your hiding — Use the replacement test: can you swap implementations without client changes?

What's Next:

Page Complete