Help us improve
Share bugs, ideas, or general feedback.
From code-craftsmanship
Reviews software designs using deep modules, information hiding, and strategic vs tactical programming. Applies when discussing module design, API complexity, class depth, or abstraction tradeoffs.
npx claudepluginhub wondelai/skills --plugin systems-architectureHow this skill is triggered — by the user, by Claude, or both
Slash command
/code-craftsmanship:software-design-philosophyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A practical framework for managing the fundamental challenge of software engineering: complexity. Apply these principles when designing modules, reviewing APIs, refactoring code, or advising on architecture decisions.
Design modules, APIs, or classes before implementing. Generates multiple approaches, evaluates depth, and avoids premature coding.
Reviews code for design smells, tight coupling, missing abstractions, and architectural risks using principles from 12 classic software engineering books like Clean Code and The Pragmatic Programmer. Use before refactors, onboarding, or design reviews.
Provides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
Share bugs, ideas, or general feedback.
A practical framework for managing the fundamental challenge of software engineering: complexity. Apply these principles when designing modules, reviewing APIs, refactoring code, or advising on architecture decisions.
The greatest limitation in writing software is our ability to understand the systems we are creating. Complexity is the enemy: it makes systems hard to understand, hard to modify, and a source of bugs. Evaluate every design decision by asking "Does this increase or decrease the overall complexity of the system?" — the goal is not zero complexity, but minimizing unnecessary complexity and concentrating the necessary kind where it can be managed.
Goal: 10/10. When reviewing or creating software designs, rate them 0-10: a 10/10 means deep modules with clean abstractions, excellent information hiding, strategic thinking, and comments that capture design intent; lower scores indicate shallow modules, leakage, or tactical shortcuts. Always give the current score and the specific improvements needed to reach 10/10.
Six principles for managing complexity and producing systems that are easy to understand and modify:
Core concept: Complexity is anything about a system's structure that makes it hard to understand and modify. It shows three symptoms — change amplification, cognitive load, and unknown unknowns — and has two causes: dependencies and obscurity.
Why it works: Naming the specific symptoms lets developers diagnose problems precisely instead of relying on vague notions of "messy code," and the two causes provide clear targets for improvement.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Change amplification | Centralize shared knowledge | Extract color constants instead of hardcoding #ff0000 in 20 files |
| Cognitive load | Reduce what developers must know | open(path) instead of requiring buffer size, encoding, lock mode |
| Unknown unknowns | Make dependencies explicit | Type systems and interfaces surface what a change affects |
| Obscurity | Name things precisely | numBytesReceived not n; retryDelayMs not delay |
See: references/complexity-symptoms.md for symptom diagnosis and how complexity accumulates.
Core concept: The best modules are deep: powerful functionality behind a simple interface. Shallow modules have complex interfaces relative to the functionality they provide — they add complexity rather than hiding it.
Why it works: The interface is the complexity a module imposes on the rest of the system; the implementation is the functionality it provides. Deep modules maximize benefit per unit of interface cost.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Deep module | Hide complexity behind simple API | file.read(path) hides disk blocks, caching, buffering, encoding |
| Classitis cure | Merge related shallow classes | RequestParser + RequestValidator + RequestProcessor → one RequestHandler |
| Interface simplicity | Fewer parameters, fewer methods | config.get(key) with sensible defaults, not 15 constructor parameters |
See: references/deep-modules.md when judging whether an abstraction pulls its weight.
Core concept: Each module should encapsulate knowledge not needed by other modules. Information leakage — one design decision reflected in multiple modules — is one of the most important red flags in software design.
Why it works: Hidden knowledge can change inside one module; leaked knowledge makes changes propagate through the system. Hiding attacks both causes of complexity: dependencies and obscurity.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Format leakage | Centralize serialization | One module owns JSON encoding/decoding, not json.dumps everywhere |
| Temporal decomposition | Organize by knowledge, not time | Combine "read config" and "apply config" into one config module |
| Protocol leakage | Abstract transport details | MessageBus.send(event) hides HTTP vs. gRPC vs. queue |
See: references/information-hiding.md for leakage red flags and decorator pitfalls.
Core concept: Design modules that are "somewhat general-purpose": an interface general enough to support multiple uses, with an implementation that handles current needs. Ask: "What is the simplest interface that will cover all my current needs?"
Why it works: General-purpose interfaces are usually simpler because they eliminate special cases, and new use cases often fit the existing abstraction — while over-generalization wastes effort on speculative complexity.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| API generality | Design for the concept, not one use case | text.insert(position, string) instead of text.addBulletPoint() |
| Reduce configuration | Determine behavior automatically | Auto-detect file encoding instead of an encoding parameter |
| Avoid over-specialization | One general method over many specific ones | store(key, value, options) instead of storeUser(), storeProduct(), storeOrder() |
See: references/general-vs-special.md when choosing how general an interface should be.
Core concept: Comments should describe what is not obvious from the code: design intent, abstraction rationale, invariants, and assumptions. "Good code is self-documenting" is a myth for anything beyond low-level implementation detail.
Why it works: Code tells you what the program does, not why, what the alternatives were, or what it assumes — comments capture the designer's mental model, the most valuable and most perishable information in a system.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Interface comment | Describe the abstraction, not the implementation | "Returns the widget closest to position, or null if none within threshold" |
| Data structure comment | Explain invariants | "List is sorted by priority descending; ties broken by insertion order" |
| Implementation comment | Explain why, not what | "// Binary search: list is always sorted, can hold 100k+ items" |
| Cross-module comment | Link related decisions | "// This timeout must match the retry interval in RetryPolicy.java" |
See: references/comments-as-design.md for comment-driven design and the self-documenting-code myth.
Core concept: Tactical programming gets features working quickly and accumulates complexity with each shortcut. Strategic programming invests 10-20% extra effort in good design, treating every change as an opportunity to improve structure.
Why it works: Tactical speed is borrowed: each shortcut makes future changes harder, while the strategic investment compounds — strategically designed systems are faster to work with within months.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Tactical trap | Resist quick-and-dirty fixes | Don't add a boolean parameter for "just this one special case" |
| Strategic investment | Improve structure during feature work | Refactor an awkward module interface while adding the feature |
| Design reviews | Evaluate structure, not just correctness | Ask "does this make the system simpler?" not just "does it work?" |
See: references/strategic-programming.md for the investment mindset and startup considerations.
| Mistake | Why It Fails | Fix |
|---|---|---|
| Creating too many small classes | Classitis adds interfaces without depth; each boundary is cognitive overhead | Merge related shallow classes into deeper modules |
| Splitting modules by temporal order | "Read, then process, then write" forces shared knowledge across modules | Group code that shares knowledge into one module |
| Exposing implementation in interfaces | Callers depend on internals; changes propagate | Design interfaces around abstractions; hide formats and protocols |
| Treating comments as optional | Design intent and assumptions are lost; newcomers guess wrong | Write interface comments first; maintain with the code |
| Configuration parameters for everything | Each parameter pushes a decision onto the caller | Determine behavior automatically; provide sensible defaults |
| Quick-and-dirty tactical fixes | Shortcuts compound until the system is unworkable | Invest 10-20% extra; treat every change as a design opportunity |
| Pass-through methods | Delegation-only methods add interface without depth | Merge the pass-through into the caller or the callee |
| Designing for specific use cases | Special-purpose interfaces accumulate special cases | Ask: simplest interface covering all current needs? |
| Question | If No | Action |
|---|---|---|
| Can you describe each module in one sentence? | Modules do too much or lack purpose | Split into coherent, describable responsibilities |
| Are interfaces simpler than implementations? | Modules are shallow — complexity leaks outward | Hide more; merge shallow classes into deeper ones |
| Can you change an implementation without affecting callers? | Information is leaking across boundaries | Encapsulate the leaked knowledge in one module |
| Do interface comments describe the abstraction? | Design intent lost; module will be misused | Document what the module promises, not how it works |
| Is design discussion part of code reviews? | Reviews catch bugs but not complexity growth | Add "does this reduce complexity?" to review criteria |
| Does each module hide an important design decision? | Modules organized around code, not information | Reorganize so each module owns specific knowledge |
| Can a newcomer understand module boundaries without reading implementations? | Abstractions undocumented or leaky | Improve interface comments; simplify interfaces |
| Are you spending 10-20% of time on design improvement? | Debt accumulates with every feature | Include design improvement in every PR |
For the complete methodology with detailed examples:
John Ousterhout is the Bosack Lerner Professor of Computer Science at Stanford and the creator of the Tcl scripting language and Tk toolkit. He developed A Philosophy of Software Design from his Stanford CS 190 course, distilling decades of systems-building experience into principles that apply across languages and scales.