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

架构

PrincipleDescription
@architecture
Imperative shell, functional core—separate pure logic from I/O
原则描述
@architecture
命令式外壳，函数式核心——将纯逻辑与I/O分离

Design Principles

设计原则

PrincipleDescription
@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

测试策略

  1. Property-based testing for pure functions—verify invariants across thousands of inputs
  2. Snapshot testing for complex data structures—catch unintended changes
  3. Integration tests for the imperative shell—verify I/O coordination
  1. 基于属性的测试 针对纯函数——在数千个输入中验证不变量
  2. 快照测试 针对复杂数据结构——捕获意外变更
  3. 集成测试 针对命令式外壳——验证I/O协调

Review Checklist

评审检查清单

When reviewing code, verify:
  • Types prevent invalid states (no interacting boolean flags)
  • Functions have single responsibility
  • Validation happens at boundaries, not scattered throughout
  • Dependencies are explicit (no hidden globals)
  • Errors surface immediately with context
  • Mutations are justified and isolated
  • No magic strings where types would work
  • No lint suppressions without explicit approval
评审代码时，请验证：
  • 类型可防止无效状态（无相互影响的布尔标志）
  • 函数具备单一职责
  • 验证在边界处进行，而非分散在各处
  • 依赖关系明确（无隐藏全局变量）
  • 错误立即附带上下文暴露
  • 变更操作具备合理性且被隔离
  • 可使用类型的场景下无魔法字符串
  • 无未经明确批准的代码检查抑制项