software-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

Opinionated guidance on classic design principles and architectural patterns, with concrete code examples and trade-off analysis.

带有明确立场的经典设计原则与架构模式指导，包含具体代码示例与权衡分析。

Diagnose first — Identify the specific design tension (coupling, cohesion, complexity, rigidity)
Name the principle — State which principle applies and why
Show the trade-off — Every principle has a cost; state it explicitly
Demonstrate with code — Before/after examples grounded in the user's codebase context

Principles are heuristics, not laws. Apply them when they reduce complexity; skip them when they add it.
Prefer boring, obvious code over clever, abstract code.
The best design is the simplest one that handles current requirements. Speculative generality is a code smell.
Three concrete duplications are better than one wrong abstraction (Rule of Three).

Principle	One-liner	Apply when...	Skip when...
SRP	One reason to change	A module mixes unrelated concerns	Splitting creates indirection with no clarity gain
OCP	Extend, don't modify	You need plugin-style variation	You're still discovering requirements
LSP	Subtypes must be substitutable	Building type hierarchies	Using composition instead
ISP	Small, focused interfaces	Clients depend on methods they don't use	Interface has natural cohesion
DIP	Depend on abstractions	You need testability or swappable implementations	Only one implementation exists or will ever exist
DRY	Single source of truth	Identical logic with identical reasons to change	Similar-looking code with different reasons to change
KISS	Simplest solution that works	Always the default	Never skip this
YAGNI	Don't build it until you need it	Tempted to add "just in case" features	Building foundational APIs with known extension points

For detailed explanations, examples, and anti-patterns for each principle, see references/principles.md.

原则	一句话总结	适用场景	避免场景
SRP	单一变更原因	模块混杂了不相关的职责	拆分后会增加间接性且无清晰度提升
OCP	扩展而非修改	需要插件式变体的场景	仍在探索需求的阶段
LSP	子类型必须可替换	构建类型层级结构时	改用组合方式实现时
ISP	小而聚焦的接口	客户端依赖了未使用的方法时	接口具有自然内聚性时
DIP	依赖抽象而非具体实现	需要可测试性或可替换实现的场景	仅存在一种实现且未来也不会有其他实现时
DRY	单一事实来源	逻辑完全相同且变更原因一致的场景	外观相似但变更原因不同的代码
KISS	最简单的可行方案	始终作为默认选择	绝不跳过此原则
YAGNI	无需则不构建	想要添加“以防万一”的功能时	构建已知有扩展点的基础API时

如需每个原则的详细解释、示例及反模式，请查看references/principles.md。

Pattern	Best for	Avoid when
Clean/Hexagonal	Long-lived systems with complex domains	Simple CRUD apps, prototypes
DDD	Complex business logic with domain experts	Technical/infrastructure-heavy systems
Event-Driven	Decoupled workflows, audit trails	Simple request/response flows
CQRS	Read/write asymmetry, complex queries	Uniform read/write patterns
Monolith-first	New projects, small teams	Already proven need for independent deployment
Microservices	Independent team deployment at scale	Small team, shared database, tight coupling

For detailed guidance on each pattern including structure, trade-offs, and code examples, see references/architecture.md.

如需每个模式的详细指导，包括结构、权衡及代码示例，请查看references/architecture.md。

When advising on design, follow this priority order:

提供设计建议时，请遵循以下优先级顺序：

Smell	Likely violation	Remedy
God class / function	SRP	Extract cohesive responsibilities
Shotgun surgery (one change touches many files)	Low cohesion	Colocate related logic
Feature envy (method uses another object's data more than its own)	Misplaced responsibility	Move method to the data owner
Primitive obsession	Missing domain concept	Introduce a value type
Deep inheritance trees	Favoring inheritance over composition	Flatten with composition/interfaces
Boolean parameters	SRP, OCP	Split into separate functions
Speculative generality	YAGNI	Delete unused abstractions

When reviewing or advising:

Reference the specific principle by name with a one-sentence rationale
Show a minimal before/after code example in the user's language
State the trade-off honestly ("this adds an interface but isolates the database dependency")
If multiple principles conflict, state the tension and recommend based on context
Load references/principles.md for deep-dive principle discussions
Load references/architecture.md for architectural pattern guidance

进行评审或提供建议时：