| name | a-philosophy-of-software-design-skills |
| description | Comprehensive guide to software design based on "A Philosophy of Software Design" by John Ousterhout. Covers complexity management, deep modules, error handling, naming, documentation, general-purpose design, design process, and consistency conventions. |
| license | MIT |
| metadata | {"version":"1.0.0","author":"Based on work by John Ousterhout","tags":"software-design, complexity, architecture, best-practices, code-quality"} |
Software Design Principles
A comprehensive guide to software design based on "A Philosophy of Software Design" by John Ousterhout.
Description
This skill provides practical guidance for writing simple, maintainable code that minimizes complexity. It covers eight essential areas of software design:
- Complexity Management - Understanding and fighting complexity through strategic programming
- Deep Modules - Creating powerful abstractions with simple interfaces
- Error Handling - Defining errors out of existence
- Naming & Obviousness - Making code self-documenting
- Documentation - Writing meaningful comments
- General-Purpose Design - Building reusable, flexible modules
- Design Process - Practical methodology and best practices
- Consistency - Leveraging conventions to reduce cognitive load
When to Use
Use this skill when:
- Designing new features or modules
- Reviewing code for quality and maintainability
- Refactoring existing code
- Establishing team coding standards
- Teaching software design principles
- Making architectural decisions
Core Philosophy
The fundamental problem in software design is managing complexity. This skill teaches you to:
- Think strategically, not tactically
- Create deep modules with simple interfaces
- Hide implementation details effectively
- Eliminate special cases and exceptions
- Write obvious, self-documenting code
- Make continual small investments in design quality
Quick Start
- Read the README for an overview
- Start with 01-complexity-management.md to understand the core philosophy
- Reference specific skills as needed during development
- Use red flags and principles as a code review checklist
Contents
README.md - Complete overview and integration guideQUICK-REFERENCE.md - One-page cheat sheetINSTALLATION.md - Installation and usage guide01-complexity-management.md - Core philosophy and strategic programming02-deep-modules.md - Interface design and information hiding03-error-handling.md - Eliminating exceptions and special cases04-naming-obviousness.md - Naming conventions and code clarity05-comments-documentation.md - Effective documentation practices06-general-purpose-design.md - Building flexible, reusable code07-design-process.md - Design methodology and workflow08-consistency-conventions.md - Standards and conventions
Each skill includes:
- Core principles and philosophy
- Practical guidelines and examples
- Good vs bad code comparisons
- Red flags to watch for
- Benefits and when to apply
Key Takeaways
Red Flags (signs of complexity):
- Shallow modules, information leakage, pass-through methods
- Vague names, hard-to-describe interfaces
- Comments that repeat code
- Special cases proliferating
- Nonobvious code requiring extensive explanation
Design Principles:
- Complexity is incremental - sweat the small stuff
- Working code isn't enough - design quality matters
- Modules should be deep (simple interface, powerful implementation)
- Define errors out of existence
- Design it twice (consider alternatives)
- Comments describe what's non-obvious
- Design for ease of reading, not writing
Attribution
Based on "A Philosophy of Software Design" by John Ousterhout, published by Yaknyam Press.
