Skip to content
Back to search

software-design-philosophy

Software design philosophy guide based on John Ousterhout's "A Philosophy of Software Design." Use this skill during: code reviews, architecture discussions, API design, module decomposition decisions, refactoring guidance, complexity analysis, naming and commenting improvements, error handling strategy design. Trigger when the user mentions "code is too complex", "how to split modules", "interface design", "reduce coupling", "deep/shallow modules", "information leakage", "error handling", "code readability", "design philosophy", "pull complexity down", "define errors out of existence", or similar topics. Also trigger for any code review where design quality feedback is requested.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/luoling8192-software-design-philosophy-skill/badge.svg)](/listings/luoling8192-software-design-philosophy-skill)

HTML

<a href="/listings/luoling8192-software-design-philosophy-skill"><img src="/api/listings/luoling8192-software-design-philosophy-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code

claude install-skill luoling8192/software-design-philosophy-skill

Codex

codex skills add luoling8192/software-design-philosophy-skill

Skills.sh (Vercel)

npx skills add luoling8192/software-design-philosophy-skill

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 291 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: software-design-philosophy
  3. description: >
  4. Software design philosophy guide based on John Ousterhout's "A Philosophy of Software Design."
  5. Use this skill during: code reviews, architecture discussions, API design, module decomposition decisions,
  6. refactoring guidance, complexity analysis, naming and commenting improvements, error handling strategy design.
  7. Trigger when the user mentions "code is too complex", "how to split modules", "interface design",
  8. "reduce coupling", "deep/shallow modules", "information leakage", "error handling", "code readability",
  9. "design philosophy", "pull complexity down", "define errors out of existence", or similar topics.
  10. Also trigger for any code review where design quality feedback is requested.
  11. ---
  12. # A Philosophy of Software Design — Distilled Guide
  13. > Source: John Ousterhout, *A Philosophy of Software Design*
  14. > Central thesis: **The core challenge of software design is managing complexity.**
  15. ---
  16. ## I. Complexity: Know the Enemy
  17. ### Definition
  18. Complexity is anything related to the structure of a software system that makes it **hard to understand and modify**. Complexity is not the same as system size — a small system can be complex, and a large well-designed system can be manageable.
  19. ### Three Symptoms of Complexity
  20. 1. **Change Amplification**: A seemingly simple change requires code modifications in many different places.
  21. 2. **Cognitive Load**: Developers must absorb a large amount of information to complete a task safely. Note: fewer lines of code ≠ simpler — sometimes more code is actually simpler because it reduces cognitive load.
  22. 3. **Unknown Unknowns**: It's unclear which code must be modified or what information is needed to complete a task. This is the most dangerous symptom.
  23. ### Two Root Causes
  24. 1. **Dependencies**: A piece of code cannot be understood or modified in isolation; it relates to other code that must also be considered.
  25. 2. **Obscurity**: Important information is not obvious — vague names, missing docs, implicit conventions, hidden constraints.
  26. ### Key Insight
  27. - **Complexity is incremental**: It's not caused by a single catastrophic error; it accumulates through thousands of small decisions.
  28. - Therefore you must adopt a **zero-tolerance** mindset — every bit of "minor" complexity matters.
  29. ---
  30. ## II. Strategic vs. Tactical Programming
  31. ### Tactical Programming (Anti-pattern)
  32. - Goal: get features working as quickly as possible.
  33. - Mindset: "Just make it work", "We'll refactor later."
  34. - Result: complexity accumulates fast, tech debt spirals out of control.
  35. ### Strategic Programming (Recommended)
  36. - Goal: produce great design; working code is a byproduct.
  37. - Mindset: **invest roughly 10–20% of development time in design improvements.**
  38. - Practices:
  39. - Look for opportunities to improve design with every change.
  40. - Working code is not enough — design quality matters equally.
  41. - The increments of software development should be **abstractions**, not features.
  42. ---
  43. ## III. Deep Modules: The Most Important Design Concept
  44. ### Core Metaphor
  45. Think of a module as a rectangle:
  46. - **Width** = complexity of its interface
  47. - **Height/Depth** = amount of functionality hidden inside
  48. **Deep module**: simple interface, rich implementation. (Good design)
  49. **Shallow module**: complex interface, does very little. (Bad design 🚩)
  50. ### Classic Examples
  51. - **Deep**: Unix file I/O — just 5 syscalls (open, read, write, lseek, close) expose a powerful file system.
  52. - **Shallow**: Java I/O — reading a file requires composing FileInputStream, BufferedInputStream, ObjectInputStream, etc.
  53. ### Practical Principles
  54. - Design interfaces so the **most common usage is as simple as possible**.
  55. - A simple interface matters more than a simple implementation.
  56. - Rare use cases can accept more complex calling patterns, but the common path should never pay for them.
  57. ---
  58. ## IV. Information Hiding and Information Leakage
  59. ### Information Hiding
  60. - Each module should encapsulate **design decisions** (knowledge), exposing only a simplified interface.
  61. - Hidden information includes: data structures, algorithms, low-level mechanisms, policy decisions.
  62. - Information hiding minimizes inter-module dependencies.
  63. ### Information Leakage 🚩 Red Flag
  64. - When the same design decision is reflected in multiple modules, information has leaked.
  65. - **Temporal decomposition** is a common source: splitting modules by execution order (rather than by information hiding) causes steps to share excessive knowledge.
  66. ### Fixing Leakage
  67. - Merge shared knowledge into a single module.
  68. - If merging isn't possible, unify the shared information behind a single deep module.
  69. ---
  70. ## V. General-Purpose vs. Special-Purpose Modules
  71. ### Core Principle: General-purpose modules are usually deeper.
  72. - A general interface is simpler than a specialized one because it covers more use cases with fewer methods.
  73. - When designing a new module, ask: **What is the most general-purpose interface that can satisfy my current needs?**
  74. ### Judgment Criteria
  75. - The interface should be general enough to support multiple use cases without modification.
  76. - But the implementation can do only what's currently needed (don't over-build).
  77. - General-purpose and special-purpose code should be **cleanly separated**.
  78. ---
  79. ## VI. Different Layers, Different Abstractions
  80. ### Principle
  81. - A software system has multiple layers; each layer should provide a **different abstraction** from its adjacent layers.
  82. - If two layers have similar abstractions, the layering is wrong.
  83. ### Pass-Through Method 🚩 Red Flag
  84. - A method that does almost nothing except forward its arguments to another method with a similar signature.
  85. - This signals that the layers don't offer different abstractions — the responsibility split is flawed.
  86. ### Pass-Through Variable 🚩 Red Flag
  87. - A variable threaded from top to bottom through layers that don't use it.
  88. - Solutions: context objects, dependency injection, or rethinking module boundaries.
  89. ---
  90. ## VII. Pull Complexity Downward
  91. ### Core Principle
  92. - When complexity is unavoidable, the **module should absorb it internally** rather than pushing it to callers.
  93. - Most modules have more users than developers — it's better for developers to suffer than for every user to suffer.
  94. ### Anti-patterns
  95. - Turning hard decisions into configuration parameters and pushing them to sysadmins.
  96. - Throwing exceptions for uncertain conditions and letting callers handle them.
  97. - These save effort in the short term but amplify complexity system-wide.
  98. ---
  99. ## VIII. Define Errors Out of Existence
  100. ### Core Insight
  101. - Exception handling is one of the biggest sources of complexity.
  102. - Reducing the number of exceptions that must be handled is one of the best techniques for reducing complexity.
  103. ### Strategies
  104. 1. **Redefine semantics so the error condition cannot arise.**
  105. - Example: `unset(key)` succeeds even if the key doesn't exist — it simply guarantees "after the call, the key does not exist."
  106. - Example: `substring(start, end)` auto-clips out-of-bounds parameters instead of throwing.
  107. 2. **Exception Masking**: Detect and handle exceptions at a low level so they never reach callers.
  108. 3. **Exception Aggregation**: Handle multiple exception types in one centralized place instead of scattering handlers at every call site.
  109. ### Important Distinction
  110. - This is not about ignoring errors — it's about **designing better semantics so error conditions simply aren't errors**.
  111. - Errors that truly require reporting (e.g., lost network packets) must still be handled properly.
  112. ---
  113. ## IX. Design It Twice
  114. - For any important design decision, conceive **at least two different approaches** before choosing.
  115. - Even if the first idea seems great, force yourself to think of an alternative.
  116. - Comparison dimensions: interface simplicity, generality, performance, implementation difficulty.
  117. - This habit significantly improves design quality.
  118. ---
  119. ## X. The Philosophy of Comments
  120. ### Why Write Comments
  121. 1. Comments capture **design decisions and intent** that code cannot express.
  122. 2. Comments are part of the abstraction — good interface docs mean users don't have to read the implementation.
  123. 3. Writing comments **early** exposes design problems before you invest in code.
  124. 4. Good comments dramatically reduce cognitive load.
  125. ### What Comments Should Describe
  126. - **Non-obvious information**: the *why*, constraints, boundary conditions, side effects — things you can't see in the code.
  127. - Comments should NOT repeat what the code already says. 🚩 Red Flag: Comment Repeats Code
  128. ### Comment Layers
  129. - **Interface comments**: describe *what* and *why* — no implementation details.
  130. - **Implementation comments**: explain *how* and *why this approach* — why the code is written this way.
  131. - **Cross-module comments**: document design decisions and dependencies that span module boundaries.
  132. ### Comments-First Approach
  133. - Write interface comments *before* writing the implementation — use comments as a design tool.
  134. - If you can't write a clear comment, the design itself probably has a problem.
  135. ---
  136. ## XI. The Art of Naming
  137. ### Standards for Good Names
  138. - **Precise**: conveys meaning to the reader without ambiguity.
  139. - **Consistent**: the same name always means the same thing across the codebase.
  140. - **Informative**: a good name is lightweight documentation by itself.
  141. ### Naming Red Flags 🚩
  142. - **Vague names**: too generic (e.g., `data`, `result`, `tmp`, `info`) — carry no useful information.
  143. - **Hard to name**: if you struggle to find a precise, intuitive name for an entity, the design itself may be flawed.
  144. ---
  145. ## XII. Consistency
  146. - Handle **the same thing the same way** throughout the entire system.
  147. - Consistency covers: naming, coding style, interface patterns, design patterns, invariants.
  148. - Consistency dramatically reduces cognitive load — once a developer learns one pattern, it applies everywhere.
  149. - Don't break consistency for "better" unless the improvement is significant enough and the old way can be fully replaced.
  150. ---
  151. ## XIII. Code Should Be Obvious
  152. ### Goal
  153. - A reader should be able to quickly understand the behavior and intent of code without significant mental effort.
  154. - Obviousness is the ultimate test of good design.
  155. ### Techniques for Obvious Code
  156. - Good naming and consistency.
  157. - Judicious use of whitespace and formatting to reveal structure.
  158. - Comments that explain the non-obvious.
  159. - Avoid implicit control flow in event-driven code (unless necessary).
  160. ### Non-Obvious Code 🚩 Red Flag
  161. - If a reader cannot easily understand the behavior or meaning of a piece of code, it is not obvious enough.
  162. ---
  163. ## XIV. Red Flags Quick Reference
  164. Use these signals during code reviews and self-reviews:
  165. | Signal | Meaning |
  166. |--------|---------|
  167. | **Shallow Module** | Interface is nearly as complex as its implementation |
  168. | **Information Leakage** | Same design decision reflected in multiple modules |
  169. | **Temporal Decomposition** | Modules split by execution order, not information hiding |
  170. | **Overexposure** | Common API forces callers to know about rarely-used features |
  171. | **Pass-Through Method** | Method just forwards args to another method with similar signature |
  172. | **Repetition** | Non-trivial code duplicated across locations |
  173. | **Special-General Mixture** | General-purpose and special-purpose code not cleanly separated |
  174. | **Conjoined Methods** | Understanding one method requires understanding another |
  175. | **Comment Repeats Code** | Comment is just an English translation of the code |
  176. | **Impl Contaminates Interface** | Interface docs expose implementation details users don't need |
  177. | **Vague Name** | Name too generic to convey useful information |
  178. | **Hard to Pick Name** | Can't find a precise, intuitive name — design may be flawed |
  179. | **Hard to Describe** | Documentation must be long to be complete — module may be too complex |
  180. | **Non-Obvious Code** | Behavior or meaning of code is not easily understood |
  181. ---
  182. ## XV. Design Principles Summary
  183. 1. Complexity is incremental — sweat the small stuff.
  184. 2. Working code isn't enough.
  185. 3. Make continual small investments to improve system design.
  186. 4. Modules should be deep.
  187. 5. Interfaces should make the most common usage as simple as possible.
  188. 6. A simple interface matters more than a simple implementation.
  189. 7. General-purpose modules are deeper.
  190. 8. Separate general-purpose and special-purpose code.
  191. 9. Different layers should have different abstractions.
  192. 10. Pull complexity downward.
  193. 11. Define errors (and special cases) out of existence.
  194. 12. Design it twice.
  195. 13. Comments should describe things not obvious from the code.
  196. 14. Software should be designed for ease of reading, not ease of writing.
  197. 15. The increments of software development should be abstractions, not features.
  198. ---
  199. ## Usage Guide
  200. Reference this guide in the following scenarios:
  201. - **Code review**: Use the Red Flags quick reference to spot design problems.
  202. - **API/Interface design**: Aim for deep modules; ensure interfaces are simple for common usage.
  203. - **Module decomposition**: Split based on information hiding, not execution order or line count.
  204. - **Error handling**: Prefer "define errors out of existence" to reduce exception propagation.
  205. - **Refactoring**: Spend 10–20% of each change improving surrounding design.
  206. - **Naming and comments**: Names should be precise; comments should describe what the code doesn't show.
README.md · README · 38 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # software-design-philosophy
  2. A reusable agent skill based on John Ousterhout's *A Philosophy of Software Design*.
  3. ## What it does
  4. This skill provides design philosophy guidance during:
  5. - Code reviews
  6. - Architecture discussions
  7. - API design
  8. - Module decomposition decisions
  9. - Refactoring
  10. - Naming and commenting improvements
  11. - Error handling strategy
  12. ## Installation
  13. ### Claude Code
  14. ```bash
  15. claude install-skill luoling8192/software-design-philosophy-skill
  16. ```
  17. ### Codex
  18. ```bash
  19. codex skills add luoling8192/software-design-philosophy-skill
  20. ```
  21. ### Skills.sh (Vercel)
  22. ```bash
  23. npx skills add luoling8192/software-design-philosophy-skill
  24. ```
  25. ## License
  26. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.