Back to Details

pragmatic-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OUTPUT FORMAT

输出格式

[SEV] file:line flag-id → fix
If clean: 
FILE: <path> ✓ SIMPLE
[SEV] file:line flag-id → fix
若代码简洁合规：
FILE: <path> ✓ SIMPLE

CORE PRINCIPLES

核心原则

Novices       → Copy-paste everything
Intermediates → Abstract everything
Experts       → Know when to do neither
Two enemies of maintainability:
  1. Horizontal bloat - Too many files/classes for simple features
  2. Vertical depth - Too many jumps to find core logic
新手       → 复制粘贴所有内容
中级开发者 → 抽象所有内容
专家       → 知道何时两者都不做
可维护性的两大敌人：
  1. 横向膨胀 - 简单功能对应过多文件/类
  2. 纵向深度 - 查找核心逻辑需要多次跳转

DETECTION CHECKS (Run in Parallel)

检测检查（并行执行）

Horizontal Bloat (Over-abstraction)

横向膨胀（过度抽象）

IDGrep PatternSmellFix
single-impl
interface I[A-Z]
+ count 
implements
= 1		Interface with 1 implDelete interface
future-proof
Factory|Strategy|Provider|Builder
Pattern with 1 productUse class directly
generic-repo
extends Base|extends Abstract|<T>
Base class with overridesInline to each class
enterprise-larpGlob 
**/*Theme*
> 5 files		11 files for dark mode1 useState
IDGrep模式代码坏味道修复方案
single-impl
interface I[A-Z]
+ 统计
implements
数量 = 1		仅含一个实现类的接口删除接口
future-proof
Factory|Strategy|Provider|Builder
仅对应一个产品的设计模式直接使用类
generic-repo
extends Base|extends Abstract|<T>
含重写逻辑的基类内联到各个子类
enterprise-larp全局匹配
**/*Theme*
> 5个文件		仅暗黑模式就对应11个文件用1个useState实现

Vertical Depth (Hide-and-seek Code)

纵向深度（藏猫猫式代码）

IDGrep PatternSmellFix
deep-callPrivate methods > 3 levels deep
this._a()
→ 
_b()
→ 
_c()
→ 
_d()
Inline or flatten
scattered-flowSteps A,B,C in separate functions
stepA(); stepB(); stepC();
Keep linear in one fn
hidden-stateHeavy use of 
this.
in methods		State buried in class membersPass as explicit params
vague-name
processData|handleStuff|doWork
Generic function names
calculateMonthlyTotal
IDGrep模式代码坏味道修复方案
deep-call私有方法嵌套超过3层
this._a()
→ 
_b()
→ 
_c()
→ 
_d()
内联或扁平化
scattered-flow步骤A、B、C分散在不同函数中
stepA(); stepB(); stepC();
保持线性逻辑在单个函数内
hidden-state方法中大量使用
this.
状态隐藏在类成员中改为显式参数传递
vague-name
processData|handleStuff|doWork
通用化函数名称改为具体名称如
calculateMonthlyTotal

Traceability Issues

可追溯性问题

IDGrep PatternSmellFix
unsearchable-errorDuplicate error stringsSame "Failed" in 5 placesUnique error codes
missing-context
throw new Error("failed")
No diagnostic contextInclude why + inputs
what-not-why
// increment i
style comments		Explains what, not whyDocument business reason
IDGrep模式代码坏味道修复方案
unsearchable-error重复的错误字符串5个地方都出现相同的"Failed"使用唯一错误码
missing-context
throw new Error("failed")
无诊断上下文添加失败原因与输入参数
what-not-why
// increment i
这类注释		仅解释做什么，未说明原因记录业务层面的原因

QUICK CHECKS

快速检查

bash
undefined
bash
undefined

Horizontal: abstraction patterns

横向：抽象模式检查

Grep("Factory|Strategy|Provider|Builder|Orchestrator", path="<dir>", output_mode="content", -n=true, head_limit=20) Grep("interface I[A-Z]|abstract class|extends Base", path="<dir>", output_mode="content", -n=true, head_limit=20)
Grep("Factory|Strategy|Provider|Builder|Orchestrator", path="<dir>", output_mode="content", -n=true, head_limit=20) Grep("interface I[A-Z]|abstract class|extends Base", path="<dir>", output_mode="content", -n=true, head_limit=20)

Vertical: call depth indicators

纵向：调用深度检查

Grep("private.*(|this._[a-z]", path="<dir>", output_mode="content", -n=true, head_limit=20) Grep("processData|handleEvent|doWork|execute()", path="<dir>", output_mode="content", -n=true, head_limit=20)
Grep("private.*(|this._[a-z]", path="<dir>", output_mode="content", -n=true, head_limit=20) Grep("processData|handleEvent|doWork|execute()", path="<dir>", output_mode="content", -n=true, head_limit=20)

Traceability: error/log patterns

可追溯性：错误/日志检查

Grep("throw new Error|console.(error|log)", path="<dir>", output_mode="content", -n=true, head_limit=20)
undefined
Grep("throw new Error|console.(error|log)", path="<dir>", output_mode="content", -n=true, head_limit=20)
undefined

REVIEW CHECKLIST

评审检查清单

When reviewing, check:
  • Jump test: Need > 3 jumps to find core logic? → Inline
  • Search test: Can grep error message → exact line? → Make unique
  • Context test: Error includes why + inputs? → Add context
  • File ratio: > 5 files for simple feature? → Consolidate
评审时需检查：
  • 跳转测试：查找核心逻辑需要跳转超过3次？→ 内联处理
  • 搜索测试：能否通过Grep错误消息定位到具体行？→ 改为唯一标识
  • 上下文测试：错误信息是否包含原因与输入参数？→ 添加上下文
  • 文件占比测试：简单功能对应超过5个文件？→ 合并文件

DECISION RULES

决策规则

Split function ONLY when:
  • Logic reused 3+ times (Rule of Three)
  • Split significantly reduces cognitive load
  • NOT just because "it's too long"
Keep linear flow:
// BAD: scattered
stepA(); stepB(); stepC();

// GOOD: visible
// Step A: validate input
if (!valid) return err;
// Step B: transform
const result = transform(data);
// Step C: persist
await save(result);
Naming for grep:
// BAD: generic
catch(e) { throw new Error("Operation failed") }

// GOOD: searchable
catch(e) { throw new Error("PAYMENT_CALC_001: Monthly total failed", { customerId, month }) }
仅在以下情况拆分函数：
  • 逻辑被复用3次及以上（三次原则）
  • 拆分后显著降低认知负荷
  • 不能仅仅因为“函数太长”就拆分
保持线性流程：
// 糟糕：分散式
stepA(); stepB(); stepC();

// 良好：可视化
// 步骤A：验证输入
if (!valid) return err;
// 步骤B：转换数据
const result = transform(data);
// 步骤C：持久化数据
await save(result);
便于Grep的命名方式：
// 糟糕：通用化
catch(e) { throw new Error("Operation failed") }

// 良好：可搜索
catch(e) { throw new Error("PAYMENT_CALC_001: Monthly total failed", { customerId, month }) }

RED FLAGS

红色警示信号

Stop if you hear:
  • "We might need this someday"
  • "This is more professional"
  • "I learned this pattern"
  • "This won't scale" (no evidence)
  • "Let's make it configurable"
若听到以下说法，需及时叫停：
  • “以后可能会用到这个”
  • “这样更专业”
  • “我学过这个设计模式”
  • “这样无法扩展”（无证据支撑）
  • “我们把它做成可配置的吧”