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

需要关注的症状

Symptom	Description
Change Amplification	Small changes require modifications in many places
Cognitive Load	Developers need excessive information to complete tasks
Unknown Unknowns	Unclear 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
在底层屏蔽异常以保护上层逻辑
使用通用处理器聚合异常
对于罕见、不可恢复的错误，直接崩溃

Symptom

Description

Change Amplification

Small changes require modifications in many places

Cognitive Load

Developers need excessive information to complete tasks

Unknown Unknowns

Unclear what code needs modification (worst symptom)

症状

描述

变更放大

微小变更需要在多处进行修改

认知负担

开发者需要大量信息才能完成任务

未知的未知

不清楚哪些代码需要修改（最严重的症状）