Imported from markduan/a-philosophy-of-software-design-skills (SKILL.md). Install upstream with npx skills add markduan/a-philosophy-of-software-design-skills. Copyright stays with the author (MIT).

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:

1. Complexity Management - Understanding and fighting complexity through strategic programming
2. Deep Modules - Creating powerful abstractions with simple interfaces
3. Error Handling - Defining errors out of existence
4. Naming & Obviousness - Making code self-documenting
5. Documentation - Writing meaningful comments
6. General-Purpose Design - Building reusable, flexible modules
7. Design Process - Practical methodology and best practices
8. 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

1. Read the README for an overview
2. Start with 01-complexity-management.md to understand the core philosophy
3. Reference specific skills as needed during development
4. Use red flags and principles as a code review checklist

Contents

• README.md - Complete overview and integration guide
• QUICK-REFERENCE.md - One-page cheat sheet
• INSTALLATION.md - Installation and usage guide
• 01-complexity-management.md - Core philosophy and strategic programming
• 02-deep-modules.md - Interface design and information hiding
• 03-error-handling.md - Eliminating exceptions and special cases
• 04-naming-obviousness.md - Naming conventions and code clarity
• 05-comments-documentation.md - Effective documentation practices
• 06-general-purpose-design.md - Building flexible, reusable code
• 07-design-process.md - Design methodology and workflow
• 08-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.