ousterhout-principles - Claude MCP Skill

# Ousterhout's Software Design Principles

Quick checks for applying John Ousterhout's "A Philosophy of Software Design" principles. Managing complexity is the primary challenge in software engineering.

## Core Formula

**Module Value = Functionality - Interface Complexity**

The best modules are **deep**: simple interfaces hiding powerful implementations.

## 1. Deep vs Shallow Module Check

### Classic Deep Module Example
**Unix I/O**: Four simple operations (open, read, write, close) hide massive complexity (buffering, disk management, filesystem, drivers, caching).

### Assessment Questions

**Functionality Assessment:**
- How much does this module actually do?
- What complexity does it hide from callers?
- Could I significantly change implementation without breaking callers?

**Interface Assessment:**
- How many public methods/functions?
- How many parameters do they require?
- How much must callers know to use it correctly?

**The Feel Test:**
- Interface complexity ≈ implementation complexity? → **Shallow** (eliminate or deepen)
- Simple interface, powerful implementation? → **Deep** (good!)
- Just wrapping another module? → **Shallow** (probably unnecessary abstraction)

### Warning Signs

❌ **Shallow Module Indicators:**
- Wrapper class exposing most wrapped methods
- Pass-through functions adding no semantic value
- Abstraction hiding little complexity
- Thin layer that could be eliminated
- Interface almost as complex as implementation

✅ **Deep Module Indicators:**
- Simple interface (few methods, clear parameters)
- Powerful functionality (does a lot)
- Hides design decisions
- Changing internals doesn't break callers
- Worth the abstraction cost

## 2. Information Leakage Check

### Core Test
**"If I change implementation details, do callers break?"**

If YES → You have information leakage.

### Common Leakage Patterns

**Database Schema Leakage:**
```
❌ BAD: Return raw database rows/arrays
   - Callers depend on column order
   - Schema changes break calling code
   - Implementation (SQL) leaks through interface

✅ GOOD: Return domain objects
   - Hide schema behind types
   - Callers use named properties
   - Schema refactoring transparent to callers
```

**Internal Data Structure Leakage:**
```
❌ BAD: Expose internal buffer/cache structure
   - Callers know about your storage choices
   - Can't change data structures freely
   - Implementation details in public API

✅ GOOD: Provide abstract query interface
   - Hide how data is stored
   - Expose "what" not "how"
   - Free to optimize internals
```

**Implementation Detail Leakage:**
```
❌ BAD: Configuration forcing caller knowledge
   - Expose internal IDs, indices, ordering
   - Require callers to know implementation
   - Changes ripple to all callers

✅ GOOD: Domain-centric interface
   - Use domain language
   - Hide technical implementation
   - Stable despite internal changes
```

### Encapsulation Check

Ask yourself:
- Can I refactor internals without breaking callers?
- Do callers know about my implementation choices?
- Does my interface reveal "how" or just "what"?
- Would changing my data structure break callers?

**Principle**: Each module should hide design decisions from others.

## 3. Red Flag Scanner

### Critical Red Flags (Avoid)

**Generic Names:**
- `Manager`, `Util`, `Helper` → Vague, non-specific
- `Service`, `Handler`, `Processor` → Sometimes justified, often lazy
- `Base`, `Abstract` → Prefix anti-patterns

**Ask**: Does name reveal **what** it does? Or just **that** it does something?

**Temporal Decomposition:**
- `step1()`, `step2()`, `step3()`
- `phase1()`, `phase2()`
- `initialize()`, `process()`, `finalize()`

**Problem**: Organized by **WHEN** executed, not **WHAT** they do.

**Better**: Organize by functionality. Name by purpose, not sequence.

### Warning Signs

**Pass-Through Methods:**
- Method just delegates to another class
- Adds no transformation or logic
- No semantic value
- Just indirection for indirection's sake

**Configuration Overload:**
- Too many parameters/options
- Every implementation detail exposed
- Interface complexity ≈ implementation
- Callers must understand internals

### Context-Aware Exceptions

Some generic names have domain justification:
- `EventManager` in event-driven system → Acceptable
- But `EventBus` or `EventDispatcher` still better (more specific)

**Principle**: Prefer specific domain terms over generic technical terms.

### Quick Scan Questions

When reviewing a module:
1. Does name reveal what it does (not just that it exists)?
2. Is it organized by execution order (temporal anti-pattern)?
3. Does it just wrap another module without adding value?
4. Could I give it a more specific, intention-revealing name?
5. Does it have too many configuration options?

## Application Workflow

**When designing:**
1. Check module depth (value = functionality - interface complexity)
2. Ensure information hiding (callers isolated from implementation)
3. Avoid red flag names (be specific, avoid generic terms)

**When reviewing:**
1. Scan for Manager/Util/Helper (red flags)
2. Test: "If implementation changes, do callers break?" (leakage)
3. Assess: Simple interface + powerful implementation? (depth)

**When refactoring:**
1. Identify shallow modules → Consider eliminating or deepening
2. Find information leakage → Add encapsulation
3. Replace generic names → Use domain-specific terms

## Key Principles Summary

1. **Deep Modules**: Simple interfaces hiding powerful implementations
2. **Information Hiding**: Each module hides design decisions from others
3. **Avoid Complexity**: Fight generic names, temporal decomposition, pass-through methods
4. **YAGNI**: Question every piece not solving an immediate need
5. **Readability Over Cleverness**: Code is read more than written

**Remember**: Complexity is anything that makes software hard to understand or modify. Fight it with every decision.

## References

- [simplicity-tenets.md](references/simplicity-tenets.md) - YAGNI, complexity types, warning signs