name: code-quality description: “代码质量标准。定义复杂度管理、模块化设计、代码异味检测。在编写或审查代码时自动应用。” user-invocable: false
编程哲学与质量标准
核心理念
- 代码主要是为了人类阅读和维护而编写的；机器执行是副产品
- 优先级：可读性与可维护性 > 正确性 > 性能 > 代码长度
- 遵循每种语言社区的惯用实践
复杂度管理
复杂度 = 依赖项 + 晦涩度
需要警惕的症状
| 症状 | 描述 |
|---|---|
| 变更放大 | 小的变更需要在多处进行修改 |
| 认知负荷 | 开发者需要过多信息才能完成任务 |
| 未知的未知 | 不清楚需要修改哪些代码（最糟糕的症状） |
缓解策略
- 对增量式复杂度增长采取“零容忍”态度
- 预先投入时间进行设计
- 避免产生技术债务的战术捷径
模块化设计原则
- 深度模块：通过简单接口提供强大功能
- 信息隐藏：将设计决策封装在实现内部
- 通用设计：对抗过度专业化
- 避免“类病”：更多的类/组件 ≠ 更好的设计
需要警惕的代码异味
主动识别并标记：
- 重复的逻辑 / 复制粘贴代码
- 过度紧密的耦合或循环依赖
- 脆弱的设计（一处变更会破坏不相关的部分）
- 意图不明确、混乱的抽象、模糊的命名
- 没有实际收益的过度工程
识别代码异味时：
- 简明扼要地解释问题
- 提供1-2个重构方向，并说明优缺点
错误处理策略
- 将错误设计掉 — 尽可能设计没有异常的API
- 在低层屏蔽异常以保护高层
- 使用通用处理程序聚合异常
- 对于罕见的、不可恢复的错误，直接崩溃