xuehua-s/fast-md5-web/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. The central thesis is that complexity is the root cause of most software problems, and managing it requires deliberate, strategic thinking at every level of design.

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. Every design decision should be evaluated by asking: "Does this increase or decrease the overall complexity of the system?" The goal is not zero complexity -- that is impossible in useful software -- but to minimize unnecessary complexity and concentrate necessary complexity where it can be managed.

Scoring

Goal: 10/10. When reviewing or creating software designs, rate them 0-10 based on adherence to the principles below. A 10/10 means deep modules with clean abstractions, excellent information hiding, strategic thinking about complexity, and comments that capture design intent. Lower scores indicate shallow modules, information leakage, tactical shortcuts, or missing design documentation. Always provide the current score and 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 related to the structure of a software system that makes it hard to understand and modify. It manifests through three symptoms: change amplification, cognitive load, and unknown unknowns.

Why it works: By identifying the specific symptoms of complexity, developers can diagnose problems precisely rather than relying on vague notions of "messy code." The two fundamental causes -- dependencies and obscurity -- provide clear targets for design improvement.

Key insights:

• Change amplification: a simple change requires modifications in many places
• Cognitive load: a developer must hold too much information in mind to make a change
• Unknown unknowns: it is not obvious what needs to be changed, or what information is relevant (the worst symptom)
• Dependencies: code cannot be understood or modified in isolation
• Obscurity: important information is not obvious from the code or documentation
• Complexity is incremental -- it accumulates from hundreds of small decisions, not one big mistake
• The "death by a thousand cuts" nature of complexity means every decision matters

Code applications:

See: references/complexity-symptoms.md

2. Deep vs Shallow Modules

Core concept: The best modules are deep: they provide powerful functionality behind a simple interface. Shallow modules have complex interfaces relative to the functionality they provide, adding complexity rather than reducing it.

Why it works: A module's interface represents the complexity it imposes on the rest of the system. Its implementation represents the functionality it provides. Deep modules give you a high ratio of functionality to interface complexity. The interface is the cost; the implementation is the benefit.

Key insights:

• A module's depth = functionality provided / interface complexity imposed
• Deep modules: simple interface, powerful implementation (Unix file I/O, garbage collectors)
• Shallow modules: complex interface, limited implementation (Java I/O wrapper classes)
• "Classitis": the disease of creating too many small, shallow classes
• Each interface adds cognitive load -- more classes does not mean better design
• The best abstractions hide significant complexity behind a few simple concepts
• Small methods are not inherently good; depth matters more than size

Code applications:

See: references/deep-modules.md

3. Information Hiding and Leakage

Core concept: Each module should encapsulate knowledge that is not needed by other modules. Information leakage -- when a design decision is reflected in multiple modules -- is one of the most important red flags in software design.

Why it works: When information is hidden inside a module, changes to that knowledge require modifying only that module. When information leaks across module boundaries, changes propagate through the system. Information hiding reduces both dependencies and obscurity, the two fundamental causes of complexity.

Key insights:

• Information hiding: embed knowledge of a design decision in a single module
• Information leakage: the same knowledge appears in multiple modules (a red flag)
• Temporal decomposition causes leakage: splitting code by when things happen forces shared knowledge across phases
• Back-door leakage through data formats, protocols, or shared assumptions is the subtlest form
• Decorators are frequent sources of leakage -- they expose the decorated interface
• If two modules share knowledge, consider merging them or creating a new module that encapsulates the shared knowledge

Code applications:

See: references/information-hiding.md

4. General-Purpose vs Special-Purpose Modules

Core concept: Design modules that are "somewhat general-purpose": the interface should be general enough to support multiple uses without being tied to today's specific requirements, while the implementation handles current needs. Ask: "What is the simplest interface that will cover all my current needs?"

Why it works: General-purpose interfaces tend to be simpler because they eliminate special cases. They also future-proof the design since new use cases often fit the existing abstraction. However, over-generalization wastes effort and can itself introduce complexity through unnecessary abstractions.

Key insights:

• "Somewhat general-purpose" is the sweet spot between too specific and too generic
• The key question: "What is the simplest interface that will cover all my current needs?"
• General-purpose interfaces are often simpler than special-purpose ones (fewer special cases)
• Push complexity downward: modules at lower levels should handle hard cases so upper levels stay simple
• Configuration parameters often represent failure to determine the right behavior -- each parameter is complexity pushed to the caller
• When in doubt, implement the simpler, more general-purpose approach first

Code applications:

See: references/general-vs-special.md

5. Comments as Design Documentation

Core concept: Comments should describe things that are not obvious from the code. They capture design intent, abstraction rationale, and information that cannot be expressed in code. The claim that "good code is self-documenting" is a myth for anything beyond low-level implementation details.

Why it works: Code tells you what the program does, but not why it does it that way, what the design alternatives were, or what assumptions the code makes. Comments capture the designer's mental model -- the abstraction -- which is the most valuable and most perishable information in a system.

Key insights:

• Four types: interface comments, data structure member comments, implementation comments, cross-module comments
• Interface comments are the most important: they define the abstraction a module presents
• Write comments first (comment-driven design) to clarify your thinking before writing code
• "Self-documenting code" works only for low-level what; it fails for why, assumptions, and abstractions
• Comments should describe what is not obvious -- if the code makes it clear, don't repeat it
• Maintain comments near the code they describe; update them when the code changes
• If a comment is hard to write, the design may be too complex

Code applications: