Back to Details

refactoring

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Refactoring

代码重构

Refactor code in small, behavior-preserving steps so the next change becomes easier, safer, and cheaper.
以不改变代码行为的微小步骤重构代码，让后续的变更更简单、更安全、成本更低。

When To Use

适用场景

  • You need to improve structure without changing externally observable behavior.
  • A feature is hard to add because the current design is awkward.
  • A bug fix is blocked by confusing, tangled, or duplicated code.
  • You need to understand legacy code before touching it.
  • You want a small, safe refactoring plan instead of a vague cleanup pass.
  • 需要在不改变外部可观测行为的前提下改进代码结构。
  • 当前设计过于笨拙，导致新增功能困难。
  • 代码混乱、耦合严重或存在重复逻辑，阻碍Bug修复。
  • 在修改遗留代码前需要先理解其逻辑。
  • 需要一个小型、安全的重构计划，而非模糊的清理工作。

When Not To Use

不适用场景

  • You are intentionally changing product behavior.
  • The code is ugly, but you do not need to touch it.
  • A rewrite is clearly cheaper and lower risk than incremental restructuring.
  • There is no practical way to verify behavior and the risk is unacceptable.
  • 有意修改产品行为时。
  • 代码虽不美观，但无需对其进行修改时。
  • 重写代码明显比增量重构成本更低、风险更小时。
  • 无法验证代码行为，且风险不可接受时。

Core Rules

核心规则

  • Refactoring is structural improvement that preserves observable behavior.
  • Refactoring is not rewriting.
  • Refactoring is not feature work.
  • Wear one hat at a time: 
    Refactor hat
    changes structure only. 
    Feature hat
    changes behavior only.
  • If both are needed, make the design change first, then make the behavioral change.
  • 重构是在保留可观测行为的前提下对代码结构进行优化。
  • 重构不等于重写。
  • 重构不等于新增功能。
  • 一次只戴一顶“帽子”： 
    Refactor hat
    仅修改代码结构。 
    Feature hat
    仅修改代码行为。
  • 若两者都需要，先进行设计变更，再修改行为。

Default Loop

默认流程

  1. Clarify the real goal: feature, bug fix, or comprehension.
  2. State the smell in one sentence.
  3. State the intended improvement in one sentence.
  4. Lock down current behavior with tests or the strongest repeatable check available.
  5. Choose the smallest refactoring that makes the next change easier.
  6. Apply one micro-step.
  7. Run checks immediately.
  8. Repeat only while improvement is still clear.
  9. Stop as soon as the intended change becomes straightforward.
Preferred step order:
  1. Rename
  2. Extract
  3. Move
  4. Encapsulate or inline
  5. Simplify conditionals
  6. Remove dead code
Before implementing the real task, first make the change easy.
Common early moves:
  • rename unclear symbols
  • extract a confusing block
  • split mixed phases
  • move logic to the data it depends on
  • remove duplication first
  1. 明确真实目标：新增功能、修复Bug或理解代码。
  2. 用一句话描述代码异味。
  3. 用一句话描述预期的改进方向。
  4. 通过测试或最强可用的可重复检查来锁定当前代码行为。
  5. 选择能让后续变更更简单的最小重构操作。
  6. 执行一个微步骤。
  7. 立即运行检查。
  8. 仅在改进方向明确时重复操作。
  9. 一旦预期变更变得简单直接，立即停止。
推荐步骤顺序：
  1. 重命名
  2. 提取
  3. 移动
  4. 封装或内联
  5. 简化条件判断
  6. 删除死代码
在执行实际任务前，先让变更变得简单。
常见的初始操作：
  • 重命名含义模糊的符号
  • 提取难以理解的代码块
  • 拆分混合的流程阶段
  • 将逻辑移至其依赖的数据所在位置
  • 先消除重复代码

Quick Chooser

快速选择指南

Use this as a quick chooser, not a rigid law:
  • Mysterious Name -> Rename
  • Duplicated Code -> Extract Function, Consolidate, Move Function
  • Long Function -> Extract Function, Split Phase
  • Long Parameter List -> Introduce Parameter Object, Preserve Whole Object
  • Global Data / Mutable Data -> Encapsulate Variable, Encapsulate Record, Separate Query from Modifier
  • Divergent Change / Shotgun Surgery -> Move Function, Extract Class, Combine related behavior
  • Feature Envy -> Move Function
  • Data Clumps -> Introduce Parameter Object, Extract Class
  • Primitive Obsession -> Replace Primitive with Object
  • Repeated Switches -> Replace Conditional with Polymorphism
  • Temporary Field -> Extract Class
  • Lazy Element / Middle Man -> Inline or remove the unnecessary indirection
  • Alternative Classes With Different Interfaces -> Rename, Move, Extract Superclass
以下为快速参考，而非硬性规定：
  • 命名模糊 -> 重命名
  • 代码重复 -> 提取函数、合并、移动函数
  • 函数过长 -> 提取函数、拆分流程阶段
  • 参数列表过长 -> 引入参数对象、保留完整对象
  • 全局数据/可变数据 -> 封装变量、封装记录、将查询与修改分离
  • 发散式变更/霰弹式修改 -> 移动函数、提取类、合并相关行为
  • 特性依恋 -> 移动函数
  • 数据泥团 -> 引入参数对象、提取类
  • 基本类型偏执 -> 用对象替换基本类型
  • 重复的分支判断 -> 用多态替代条件判断
  • 临时字段 -> 提取类
  • 惰性元素/中间人 -> 内联或移除不必要的间接层
  • 接口不同的相似类 -> 重命名、移动、提取超类

Safety Rules

安全规则

  • Never let the code stay broken between steps.
  • Prefer local, reversible edits before architectural ones.
  • Prefer explicit names over clever abstraction.
  • Prefer many small commits over one large commit.
  • If tests fail, assume the last step is wrong until proven otherwise.
  • Revert aggressively instead of debugging a giant diff.
  • Keep public interfaces stable unless changing them is part of the task.
  • When an interface must change across boundaries, use compatibility shims or staged migration.
  • Do not refactor unrelated areas just because they are ugly.
  • Leave the touched area a bit healthier than you found it.
  • 绝不允许代码在步骤之间处于损坏状态。
  • 在进行架构层面修改前，优先选择局部、可回滚的编辑操作。
  • 优先使用明确的命名，而非巧妙的抽象。
  • 优先提交多个小的变更，而非一个大的提交。
  • 若测试失败，先假设最后一步操作有误，直至证明并非如此。
  • 积极回滚，而非调试巨大的差异。
  • 除非变更接口是任务的一部分，否则保持公共接口稳定。
  • 当跨边界的接口必须变更时，使用兼容性垫片或分阶段迁移。
  • 不要仅仅因为代码丑陋就重构无关区域。
  • 让你接触过的代码比之前更健康一点。

Verification Ladder

验证层级

Use the strongest available verification, in this order:
  1. existing automated tests
  2. new characterization tests
  3. deterministic integration checks
  4. reproducible manual checks
按以下顺序使用最强可用的验证方式：
  1. 现有自动化测试
  2. 新增特征测试
  3. 确定性集成检查
  4. 可重复的手动检查

Working Heuristics

工作启发法

  • In legacy code, improve the area you must touch instead of trying to beautify everything.
  • In low-test systems, choose especially safe transformations and verify constantly.
  • Do not mix performance tuning into routine refactoring. First improve clarity, then measure, then optimize only where evidence demands it.
  • Long-lived feature branches make refactoring harder. Integrate frequently and keep branch lifetime short.
  • Stop when the next intended change is easy and the design is no longer clearly improving.
  • 对于遗留代码，仅改进你必须接触的区域，而非试图美化所有内容。
  • 在测试覆盖率低的系统中，选择特别安全的转换方式，并持续验证。
  • 不要在常规重构中混入性能调优。先提升代码清晰度，再进行测量，仅在有证据表明需要优化时才进行。
  • 长期存在的功能分支会让重构更困难。频繁集成，缩短分支生命周期。
  • 当预期的下一次变更变得简单，且设计无法再明显改进时，停止重构。

Definition Of Done

完成标准

A refactoring task is done only when:
  • observable behavior is preserved
  • tests or equivalent checks pass
  • the target area is easier to understand
  • the next intended change is easier than before
  • no unnecessary abstraction was introduced
重构任务完成的标准：
  • 可观测行为保持不变
  • 测试或等效检查通过
  • 目标区域更易于理解
  • 预期的下一次变更比之前更简单
  • 未引入不必要的抽象

Reference Strategy

参考策略

Stay in this file by default. Read references only when the default loop is not enough:
  • references/01-core-principles.md
    Use when you need the core definition, the "two hats" model, or the decision standard for good design.
  • references/02-workflow-and-tactics.md
    Use when you need the execution loop, preferred step order, verification ladder, or common refactoring tactics.
  • references/03-bad-smells-map.md
    Use when you can tell the code is bad but need help naming the smell and choosing the first move.
  • references/04-refactoring-priority.md
    Use when you want to prioritize which refactorings to learn or reach for first.
  • references/05-fowler-statement-example.md
    Use when you want a concrete Fowler-style example of the rhythm in practice.
  • references/06-team-process-and-tradeoffs.md
    Use when the refactor is long-running, low-test, performance-sensitive, cross-boundary, or collaboration-heavy.
默认情况下请留在本文件中。仅当默认流程不足以解决问题时，再阅读参考资料：
  • references/01-core-principles.md
    当你需要核心定义、“双角色”模型或良好设计的决策标准时使用。
  • references/02-workflow-and-tactics.md
    当你需要执行流程、推荐步骤顺序、验证层级或常见重构策略时使用。
  • references/03-bad-smells-map.md
    当你能察觉到代码存在问题，但需要帮助命名代码异味并选择初始操作时使用。
  • references/04-refactoring-priority.md
    当你想优先学习或选择哪种重构方式时使用。
  • references/05-fowler-statement-example.md
    当你需要一个具体的Fowler风格的实践节奏示例时使用。
  • references/06-team-process-and-tradeoffs.md
    当重构耗时较长、测试覆盖率低、对性能敏感、跨边界或需要大量协作时使用。

Response Style

响应风格

When using this skill, report progress as:
  1. smell observed
  2. chosen micro-refactoring
  3. verification performed
  4. resulting improvement
使用本技能时，按以下方式报告进度：
  1. 观察到的代码异味
  2. 选择的微重构操作
  3. 执行的验证操作
  4. 带来的改进效果

Default Output Contract

默认输出约定

When asked to refactor, produce:
  • a short diagnosis of the smell
  • the minimal refactoring plan
  • the ordered micro-steps
  • the verification method
  • the final code change
当被要求进行重构时，需输出：
  • 对代码异味的简短诊断
  • 最小化的重构计划
  • 有序的微步骤
  • 验证方法
  • 最终的代码变更

One-Line Principle

一句话原则

For each desired change, first make the change easy, then make the easy change.
对于每个想要实现的变更，先让变更变得简单，再完成这个简单的变更。