ryanthedev/code-foundations/aposd-designing-deep-modules

Skill: aposd-designing-deep-modules

Before Implementing — the design-it-twice gate

Never implement your first design. Generate 2-3 radically different approaches, compare them, then implement.

Design-It-Twice Workflow

BEFORE implementing any module:
 
1. DEFINE - What are you designing? (class, API, service)
2. GENERATE - 2-3 RADICALLY different approaches
3. SKETCH - Rough outline each (important methods only, no implementation)
4. COMPARE - List pros/cons, especially ease of use for callers
5. EVALUATE - Is there a clear winner or hybrid?
6. VERIFY - Does chosen design pass depth evaluation?
7. IMPLEMENT - Only then write the code

If none attractive: Use identified problems to drive a new iteration of step 2.

Depth Evaluation

Exemplar: Unix file I/O - 5 methods hide hundreds of thousands of lines of implementation.

Three Questions Framework

Ask these when designing interfaces:

Information Hiding Checklist

When embedding functionality in a module:

• [ ] Data structures and algorithms stay internal
• [ ] Lower-level details (page sizes, buffer sizes) hidden
• [ ] Higher-level assumptions (most files are small) hidden
• [ ] No knowledge shared across module boundaries unnecessarily
• [ ] Common case requires no knowledge of internal details

Generality Sweet Spot

Target: Somewhat general-purpose

Push specialization UP: Top-level code handles specific features; lower layers stay general.

Push specialization DOWN: Define general interface, implement with device-specific variants.

Red Flags

Mandatory Output Format

When designing, produce:

## Design: [Component Name]
 
### Approaches Considered
1. [Approach A] - [1-2 sentence description]
2. [Approach B] - [1-2 sentence description]
3. [Approach C] - [1-2 sentence description] (if applicable)
 
### Comparison
| Criterion | A | B | C |
|-----------|---|---|---|
| Interface simplicity | | | |
| Information hiding | | | |
| Caller ease of use | | | |
| [Domain-specific criterion] | | | |
 
### Choice: [A/B/C/Hybrid]
Rationale: [Why this wins, what's sacrificed]
 
### Depth Check
- Interface methods: [count]
- Hidden details: [list]
- Common case complexity: [simple/moderate/complex]