software-design-philosophy

# A Philosophy of Software Design Framework 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. ## Core Principle **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. ## Scoring **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. ## The Software Design Framework Six principles for managing complexity and producing systems that are easy to understand and modify: ### 1. Complexity and Its Causes **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 h...