Loading...

Back to Details

principles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Quality Principles

代码质量原则

These principles guide all code review and quality assessment. Each principle has detailed examples in both Rust and TypeScript.

这些原则指导所有代码评审和质量评估工作。每个原则都配有Rust和TypeScript的详细示例。

Architecture

架构

Principle	Description
`@architecture`	Imperative shell, functional core—separate pure logic from I/O

原则	描述
`@architecture`	命令式外壳，函数式核心——将纯逻辑与I/O分离

Design Principles

设计原则

Principle	Description
`@illegal-states`	Make illegal states unrepresentable via type design
`@single-responsibility`	One reason to change per unit
`@parse-dont-validate`	Validated types at boundaries
`@composition`	Prefer composition over inheritance
`@open-closed`	Open for extension, closed for modification
`@explicit-dependencies`	No hidden globals or implicit state
`@fail-fast`	Surface errors immediately with context
`@domain-errors`	Errors should be identifiable to allow action
`@immutability`	Const/readonly by default
`@no-stringly-typed`	Unions/enums over magic strings
`@happy-path`	Left-hand side is the happy path (Go style early returns)

原则	描述
`@illegal-states`	通过类型设计让非法状态无法被表示
`@single-responsibility`	每个单元只有一个变更理由
`@parse-dont-validate`	在边界处使用已验证的类型
`@composition`	优先使用组合而非继承
`@open-closed`	对扩展开放，对修改关闭
`@explicit-dependencies`	无隐藏全局变量或隐式状态
`@fail-fast`	立即附带上下文暴露错误
`@domain-errors`	错误应可被识别以便采取行动
`@immutability`	默认使用Const/Readonly
`@no-stringly-typed`	使用联合类型/枚举替代魔法字符串
`@happy-path`	左侧为正常路径（Go风格提前返回）

Code-Level Standards

代码级标准

Clarity over brevity: Explicit, readable code over clever one-liners
Reduce nesting: Use early returns to flatten conditionals
Eliminate redundancy: Remove duplicate logic and dead code
No workarounds: Fix root causes, never suppress lints without explicit approval

清晰优先于简洁：优先选择明确、易读的代码，而非巧妙的单行代码
减少嵌套：使用提前返回来扁平化条件判断
消除冗余：移除重复逻辑和死代码
不使用变通方案：修复根本原因，未经明确批准绝不抑制代码检查提示

Testing Strategy

测试策略

Property-based testing for pure functions—verify invariants across thousands of inputs
Snapshot testing for complex data structures—catch unintended changes
Integration tests for the imperative shell—verify I/O coordination

基于属性的测试 针对纯函数——在数千个输入中验证不变量
快照测试 针对复杂数据结构——捕获意外变更
集成测试 针对命令式外壳——验证I/O协调

Review Checklist

评审检查清单