Principles for building reusable coding systems. Use when designing modules, APIs, CLIs, or any code meant to be used by others. Based on "A Philosophy of Software Design" by John Ousterhout...
Principles for building reusable, maintainable coding systems. From "A Philosophy of Software Design" by John Ousterhout.
Complexity is the root cause of most software problems. It accumulates incrementally—each shortcut adds a little, until the system becomes unmaintainable.
Complexity defined: Anything that makes software hard to understand or modify.
Symptoms:
The most important design principle: make modules deep.
┌─────────────────────────────┐
│ Simple Interface │ ← Small surface area
├─────────────────────────────┤
│ │
│ │
│ Deep Implementation │ ← Lots of functionality
│ │
│ │
└─────────────────────────────┘
Deep module: Simple interface, lots of functionality hidden behind it.
Shallow module: Complex interface relative to functionality provided. Red flag.
Deep: Unix file I/O - just 5 calls (open, read, write, lseek, close) hide enormous complexity (buffering, caching, device drivers, permissions, journaling).
Shallow: Java's file reading requires BufferedReader wrapping FileReader wrapping FileInputStream. Interface complexity matches implementation complexity.
Tactical: Get it working now. Each task adds small complexities. Debt accumulates.
Strategic: Invest time in good design. Slower initially, faster long-term.
Progress
│
│ Strategic ────────────────→
│ /
│ /
│ / Tactical ─────────→
│ / ↘ (slows down)
│ /
└──┴─────────────────────────────────→ Time
Rule of thumb: Spend 10-20% of development time on design improvements.
"Working code" is not the goal. The goal is a great design that also works. If you're satisfied with "it works," you're programming tactically.
Each module should encapsulate knowledge that other modules don't need.
Information leakage (red flag): Same knowledge appears in multiple places. If one changes, all must change.
Temporal decomposition (red flag): Splitting code based on when things happen rather than what information they use. Often causes leakage.
Exceptions add complexity. The best way to handle them: design so they can't happen.
Instead of:
function deleteFile(path: string): void {
if (!exists(path)) throw new FileNotFoundError();
// delete...
}
Do:
function deleteFile(path: string): void {
// Just delete. If it doesn't exist, goal is achieved.
// No error to handle.
}
Somewhat general-purpose modules are deeper than special-purpose ones.
Not too general: Don't build a framework when you need a function.
Not too specific: Don't hardcode assumptions that limit reuse.
Sweet spot: Solve today's problem in a way that naturally handles tomorrow's.
When complexity is unavoidable, put it in the implementation, not the interface.
Bad: Expose complexity to all callers. Good: Handle complexity once, internally.
It's more important for a module to have a simple interface than a simple implementation.
Configuration: Instead of requiring callers to configure everything, provide sensible defaults. Handle the complexity of choosing defaults internally.
Before implementing, consider at least two different designs. Compare them.
Benefits:
Don't skip this: "I can't think of another approach" usually means you haven't tried hard enough.
| Red Flag | Symptom |
|---|---|
| Shallow module | Interface complexity ≈ implementation complexity |
| Information leakage | Same knowledge in multiple modules |
| Temporal decomposition | Code split by time, not information |
| Overexposure | Too many methods/params in interface |
| Pass-through methods | Method does little except call another |
| Repetition | Same code pattern appears multiple times |
| Special-general mixture | General-purpose code mixed with special-purpose |
| Conjoined methods | Can't understand one without reading another |
| Comment repeats code | Comment says what code obviously does |
| Vague name | Name doesn't convey much information |
When building CLIs, plugins, or tools:
# Deep: one command handles the common case well
swarm setup
# Not shallow: doesn't require 10 flags for basic usage
# Sensible defaults: picks reasonable models
# Progressive: advanced users can customize later
