code-simplification

name	code-simplification
description	Reduce complexity while preserving behavior. Use when code works but is harder to read or maintain than it should be.

代码简化

概述

在不改变外部行为的前提下，降低代码复杂度，提升可读性和可维护性。简化的核心原则：先理解，再动手。

何时使用

• 代码功能正确但阅读困难
• 函数或文件过长，难以理解
• 条件嵌套过深，逻辑分支混乱
• 存在明显的重复或死代码
• 代码审查中发现了可简化的部分
• 不适用于：功能尚未实现或不正确的代码（先修复，再简化）

核心流程

原则 1：Chesterton's Fence——理解后再移除

"不要拆除一道你不明白为什么存在的篱笆。"

• 在删除或重构任何看似冗余的代码之前，必须先理解其原始意图
• 通过 Git Blame、注释、关联 Issue 查找历史原因
• 如果无法理解，保留代码并添加 TODO，不要贸然删除

原则 2：Rule of 500——函数不超过 500 行

• 如果一个函数超过 500 行，几乎一定可以拆分
• 拆分的依据不是行数平分，而是职责边界
• 目标：每个函数只做一件事（Single Responsibility）

简化技术

技术	做法	效果
移除死代码	删除未使用的 import、变量、函数、注释代码块	减少认知负担，消除误导
折叠条件	合并嵌套的 if/else，使用逻辑运算符化简布尔表达式	降低分支复杂度
提前返回	将前置条件检查提前 return，减少 else 嵌套	扁平化逻辑
提取辅助函数	将一段独立逻辑提取为命名函数	提升可读性和复用性
统一错误处理	使用统一的错误处理和返回模式	减少重复的模式代码
语义化命名	将复杂表达式赋值给有意义的中间变量	自文档化
消除魔法值	将硬编码常量提取为命名常量	降低修改成本和误解风险
简化数据结构	用更简单的数据结构（如基本类型而非包装类）	减少心智负担

重要约束

• 简化不改变行为——简化前后需保持完全相同的输入/输出行为
• 单独提交——简化应该只包含简化，不混入功能变更
• 有测试覆盖——简化前确保有足够的测试，简化后测试全部通过
• 逐步进行——一次简化一个方面，每次改动后都运行测试

常见错误归因

合理化	现实
"这段代码虽然复杂但能跑，别碰"	复杂度带来维护成本，简化是对未来的投资
"先拆了再说，不行再改回来"	不理解就动手会导致行为改变，且"改回来"很少发生
"重构和加功能一起做，省时间"	混合同步变更降低审查质量，出问题时无法定位
"别人写的代码太乱，重写吧"	重写损失了历史知识和已修复的 bug 信息

红色警告

• ❌ 在简化过程中引入功能变化
• ❌ 移除不理解用途的代码（未做 Chesterton's Fence）
• ❌ 一次简化改动量过大（超过 300 行变更）
• ❌ 简化后没有运行测试
• ❌ 将"没有测试"作为简化不做的借口（先加测试再简化）

验证清单

• 简化前后行为完全一致（相同输入 → 相同输出）
• 现有测试全部通过
• 如果没有测试，是否为简化添加了关键场景的覆盖？
• 每次简化改动聚焦于一个方面，没有混入功能变更
• 被删除或修改的代码已通过 Git Blame 或注释理解其原始意图
• 函数不再超过 500 行（理想情况下不超过 100 行）
• 命名和结构比简化前更清晰
• CI/Lint 通过，无新增警告