Back to Details

code-quality

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Programming Philosophy and Quality Standards

编程理念与质量标准

Core Philosophy

核心理念

  • Code is primarily written for humans to read and maintain; machine execution is a by-product
  • Priority: Readability & Maintainability > Correctness > Performance > Code length
  • Follow idiomatic practices of each language community
  • 代码主要是为人类阅读和维护而编写的；机器执行只是附带产物
  • 优先级：可读性与可维护性 > 正确性 > 性能 > 代码长度
  • 遵循各语言社区的惯用实践

Complexity Management

复杂度管理

Complexity = Dependencies + Obscurity
Complexity = Dependencies + Obscurity

Symptoms to Watch For

需要关注的症状

SymptomDescription
Change AmplificationSmall changes require modifications in many places
Cognitive LoadDevelopers need excessive information to complete tasks
Unknown UnknownsUnclear what code needs modification (worst symptom)
症状描述
变更放大微小变更需要在多处进行修改
认知负担开发者需要大量信息才能完成任务
未知的未知不清楚哪些代码需要修改（最严重的症状）

Mitigation Strategies

缓解策略

  • "Zero tolerance" for incremental complexity growth
  • Invest time upfront in design
  • Avoid tactical shortcuts that create technical debt
  • 对增量复杂度增长采取“零容忍”态度
  • 提前在设计上投入时间
  • 避免会产生技术债务的权宜之计

Modular Design Principles

模块化设计原则

  • Deep Modules: Powerful functionality through simple interfaces
  • Information Hiding: Encapsulate design decisions within implementations
  • General-Purpose Design: Combat over-specialization
  • Avoid "Classitis": More classes/components ≠ better design
  • 深度模块：通过简单接口实现强大功能
  • 信息隐藏：将设计决策封装在实现内部
  • 通用化设计：避免过度特化
  • 避免“类膨胀”：类/组件数量多≠设计好

Code Smells to Watch For

需要关注的代码异味

Proactively identify and flag:
  • Duplicated logic / copy-paste code
  • Over-tight coupling or circular dependencies
  • Fragile designs where one change breaks unrelated parts
  • Unclear intent, confused abstractions, vague naming
  • Over-engineering without real benefit
When identifying code smells:
  • Explain the problem concisely
  • Provide 1–2 refactoring directions with pros/cons
主动识别并标记：
  • 重复逻辑/复制粘贴代码
  • 过度紧耦合或循环依赖
  • 脆弱设计：一处变更会破坏无关部分
  • 意图不明确、抽象混乱、命名模糊
  • 无实际收益的过度设计
识别代码异味时：
  • 简洁地解释问题
  • 提供1–2个带有优缺点的重构方向

Error Handling Strategy

错误处理策略

  • Define errors out of existence — design APIs with no exceptions when possible
  • Mask exceptions at low levels to protect higher layers
  • Aggregate exceptions with general-purpose handlers
  • Just crash for rare, unrecoverable errors
  • 从根源消除错误——尽可能设计无异常的API
  • 在底层屏蔽异常以保护上层逻辑
  • 使用通用处理器聚合异常
  • 对于罕见、不可恢复的错误，直接崩溃