Code Simplification Zh

---
name: code-simplification-zh
description: 代码化简、可读性重构、行为不变的整理。当用户说「这段代码太绕了帮我理顺」「功能能跑但太乱」「简化一下这个函数」「嵌套太深」「去掉没用的抽象」「重构但别改行为」「让新人能看懂」时使用。五条原则：行为一字不改、跟随项目约定、清晰优先于聪明、别过度化简、只动改过的代码；流程：先懂（切斯特顿的栅栏）→ 按信号清单找机会（深嵌套/长函数/嵌套三元/布尔参数/泛名/死代码）→ 一次一改跑测试 → 复核；附 TS/Python/React 示例与合理化借口对照表。也覆盖「别改行为」「嵌套三元」「可读性差」这类说法。改编自 addyosmani/agent-skills 的 code-simplification（MIT）。
author: Captain
version: 0.1.1
display_name: "代码化简（行为不变）"
display_name_en: "Code Simplification (zh)"
description_zh: "在不改变行为的前提下让代码更好读：五原则、信号清单、一次一改跑测试、复核；含 TS/Python/React 示例。"
description_en: "Make code easier to read without changing behaviour: five principles, a signal checklist, one change at a time with tests, and a final review; TS/Python/React examples."
tags:
  - "代码化简"
  - "重构"
  - "refactoring"
  - "可读性"
  - "code review"
  - "TypeScript"
  - "Python"
  - "React"
examples_zh:
  - "把这个 200 行的函数理顺，别改行为"
  - "这段嵌套三元太绕了，帮我简化"
  - "评审时说可读性差，怎么改"
examples_en:
  - "Untangle this 200-line function without changing behaviour"
  - "This nested ternary is unreadable, simplify it"
  - "Review flagged readability, how do I fix it"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "🧹" } }
---

# 代码化简（行为不变）

目标不是更少的行数，是**新同事更快看懂**。每一处化简都要过一道题："换个人来读，会比原来快吗？"

## 什么时候用 / 不用

用：功能已通过测试但实现比需要的重；评审指出可读性或复杂度；深嵌套、长函数、名字不清；赶工写的代码；合并后出现重复。
不用：代码已经干净；你还没看懂它（先懂再改）；性能关键路径且"更简单"的版本可度量地更慢；这个模块马上要重写。

## 五条原则

1. **行为一字不改。** 输入、输出、副作用、错误行为、边界情况全部保持一致。不确定就不改。改前自问：每个输入的输出相同吗？错误行为相同吗？副作用与顺序相同吗？现有测试不改一行也能过吗？
2. **跟随项目约定。** 化简是让代码更像这个仓库，不是把你的偏好带进来：先读项目规范文件与邻近代码，对齐 import 顺序、函数声明风格、命名、错误处理、类型标注深度。破坏一致性的化简是折腾，不是化简。
3. **清晰优先于聪明。** 紧凑但要停下来想一下才能读的写法，不如多几行的直白写法。
4. **别过度化简。** 四个陷阱：把给概念命名的小函数内联掉；把两个简单函数合成一个复杂函数；删掉为扩展性/可测性存在的抽象；为行数优化。
5. **只动改过的代码。** 默认只化简最近修改的部分；顺手重构无关代码会制造噪音 diff 和回归风险。

## 流程

### 第 1 步：先懂再动（切斯特顿的栅栏）

看到路上一道栅栏，不知道为什么在那，就别拆。改之前回答：这段代码负责什么；谁调用它、它调用谁；边界与错误路径；有没有定义预期行为的测试；为什么可能这么写（性能？平台限制？历史原因？）；`git blame` 看原始上下文。答不上来就再读。

### 第 2 步：按信号找机会

**结构复杂度**

| 信号 | 表现 | 化简 |
|---|---|---|
| 嵌套 ≥ 3 层 | 控制流难跟 | 提前返回的卫语句，或抽小函数 |
| 函数 ≥ 50 行 | 多重职责 | 拆成命名清楚的小函数 |
| 嵌套三元 | 要用脑子压栈 | if/else、switch 或查表 |
| 布尔参数标志 | `doThing(true, false, true)` | 选项对象或拆成两个函数 |
| 同一条件反复出现 | 多处同样的 `if` | 抽成命名的谓词函数 |

**命名与可读性**

| 信号 | 表现 | 化简 |
|---|---|---|
| 泛名 | `data` `result` `temp` `val` `item` | 改成描述内容的名字：`userProfile` `validationErrors` |
| 缩写 | `usr` `cfg` `btn` `evt` | 用全词，除非缩写是通用的（`id` `url` `api`） |
| 名不副实 | 叫 `get` 却改状态 | 改成反映真实行为的名字 |
| 解释"做什么"的注释 | `// 计数器加一` | 删掉，代码已经说清 |
| 解释"为什么"的注释 | `// 重试是因为该 API 高负载下不稳定` | 保留，这是代码表达不了的意图 |

**冗余**

| 信号 | 表现 | 化简 |
|---|---|---|
| 重复逻辑 | 同样 5+ 行出现多处 | 抽共享函数 |
| 死代码 | 不可达分支、未用变量、注释掉的块 | 确认真死后删除 |
| 无价值包装 | 只是转发的 wrapper | 内联，直接调用 |
| 过度设计 | 工厂的工厂、只有一个策略的策略模式 | 换成直接写法 |
| 多余类型断言 | 断言成已推断出的类型 | 删掉 |

### 第 3 步：一次一改，跑测试

每做一处化简就跑一遍测试：过了就提交（或继续下一处），挂了就回退重想。不要把多处化简攒成一次未测试的大改——出问题时你得知道是哪一处。
**重构与功能/修复分开提交。** 一个 PR 既重构又加功能，就是两个 PR。
**500 行规则**：一次重构要碰 500 行以上，就投资自动化（codemod、AST 变换、sed），手改在这个规模上既易错又没法评审。

### 第 4 步：复核整体

对比前后：真的更好懂了吗？有没有引入和仓库不一致的新写法？diff 干净可评审吗？同事会批准吗？如果"化简版"反而更难读，回退——不是每次化简都成功。

## 语言示例

TypeScript：去掉多余的 `async/await` 包装；`let x; if (a) x = a; else x = b;` → `const x = a || b`（注意 `||` 与 `??` 的空值语义差异）；手动循环 push → `filter`；`if (cond) return true; return false;` → `return cond`。
Python：循环建字典 → 字典推导；三层嵌套 `if` → 提前 `raise` 的卫语句。
React：分支返回两个几乎一样的 JSX → 先算 `variant`/`label` 再返回一份；多层 prop drilling 是判断题——标出来，别自动重构。

## 合理化借口对照

| 借口 | 现实 |
|---|---|
| "能跑就别碰" | 难读的代码坏掉时也难修；现在化简，以后每次改都省时间 |
| "行数少就是简单" | 一行嵌套三元不比五行 if/else 简单；简单是理解速度，不是行数 |
| "顺手把旁边也简化了" | 无关改动让 diff 变吵、引入你没打算改的回归 |
| "类型就是文档" | 类型说明结构，不说明意图；好名字解释 why，类型只解释 what |
| "这个抽象以后可能有用" | 现在没用就是没价值的复杂度；删掉，需要时再加 |
| "原作者肯定有理由" | 也许。查 blame、用栅栏原则；但很多复杂度只是赶工的残渣 |
| "加功能时顺便重构" | 分开。混在一起难评审、难回滚、难读历史 |

## 红灯

化简后必须改测试才能过（你很可能改了行为）；"化简版"更长更难读；按个人偏好改名；为了"干净"删掉错误处理；化简自己没看懂的代码；一大坨化简塞进一个提交；未经要求动任务范围外的代码。

## 验收

```
- [ ] 现有测试不改一行全部通过 　- [ ] 构建无新警告 　- [ ] lint/格式化通过
- [ ] 每处化简都是可评审的小改动 　- [ ] diff 里没有无关改动 　- [ ] 遵循项目约定
- [ ] 没有删除或削弱错误处理 　- [ ] 没留下死代码（未用 import、不可达分支）
- [ ] 同事或评审 agent 会认为这是净改进
```

---
改编自 [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) 的 `code-simplification`（MIT）。改动见 ATTRIBUTION.md。