// Use when designing modules, APIs, or classes before implementation.
| name | aposd-designing-deep-modules |
| description | Use when designing modules, APIs, or classes before implementation. |
Never implement your first design. Generate 2-3 radically different approaches, compare them, then implement.
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
Time bound: Smaller modules: 1-2 hours. Larger modules: scale proportionally. This is design time, not implementation time.
If none attractive: Use identified problems to drive a new iteration of step 2.
| Metric | Deep (Good) | Shallow (Bad) |
|---|---|---|
| Interface size | Few methods | Many methods |
| Method reusability | Multiple use cases | Single use case |
| Hidden information | High | Low |
| Caller cognitive load | Low | High |
| Common case | Simple | Complex |
Exemplar: Unix file I/O - 5 methods hide hundreds of thousands of lines of implementation.
Ask these when designing interfaces:
| Question | Purpose | Red Flag Answer |
|---|---|---|
| "What is the simplest interface that covers all current needs?" | Minimize method count | "I need many methods" |
| "In how many situations will this method be used?" | Detect over-specialization | "Just this one situation" |
| "Is this easy to use for my current needs?" | Guard against over-generalization | "I need lots of wrapper code" |
When embedding functionality in a module:
Target: Somewhat general-purpose
| Aspect | Should Be |
|---|---|
| Functionality | Reflects current needs |
| Interface | Supports multiple uses |
| Specialization | Pushed up to callers OR down into variants |
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 Flag | Symptom | Fix |
|---|---|---|
| Shallow Module | Interface complexity rivals implementation | Combine with related functionality |
| Classitis | Many small classes with little functionality each | Consolidate related classes |
| Single-Use Method | Method designed for exactly one caller | Generalize to handle multiple cases |
| Information Leakage | Same knowledge in multiple modules | Consolidate in single module |
| Temporal Decomposition | Structure mirrors execution order | Structure by knowledge encapsulation |
| False Abstraction | Interface hides info caller actually needs | Expose necessary information |
| Granularity Mismatch | Caller must do work that belongs in module | Move logic into module |
Before finalizing your design choice, verify:
If user expresses impatience: Acknowledge it, but complete the process. Say: "I hear the urgency - this comparison takes 2 minutes and helps avoid rework."
Skip the normal workflow ONLY when ALL of these conditions are true:
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]
| After | Next |
|---|---|
| Design chosen | cc-pseudocode-programming |
Use when reviewing code, assessing interfaces, during PR review, or evaluating 'is this too complex?' Triggers on: code review, design review, module complexity, interface assessment, PR review, structural analysis.
Use when code is too complex, has scattered error handling, configuration explosion, or callers doing module work. Triggers on: too complex, simplify, scattered errors, configuration proliferation, verbose error handling
Use after implementing code. Triggers on: is it done, ready to commit, verify correctness, did I miss anything, pre-commit check.
Use when code has deep nesting (3+ levels), complex conditionals, loop design questions, high cyclomatic complexity (McCabe >10), or callback hell. Symptoms: arrow-shaped code, repeated conditions, confusing loop exits, lengthy if-else chains
Use when auditing defensive code, designing barricades, choosing assertion vs error handling, or deciding correctness vs robustness strategy. Triggers on: empty catch blocks, missing input validation, assertions with side effects, wrong exception abstraction level, garbage in garbage out mentality, deadline pressure to skip validation, trusted source rationalization.
Use when designing routines, stuck on where to start coding, caught in compile-debug loops, or code works but you don't understand why. Triggers on: starting a new coding task