python-refactoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python 代码重构

Python Code Refactoring

对 Python 代码进行系统性重构，在不改变外部行为的前提下改善内部结构，提升可读性、可维护性和可扩展性。

Systematically refactor Python code to improve internal structure, readability, maintainability, and extensibility without changing external behavior.

Overview

适用场景：代码重构、代码审查、代码质量改善、技术债务清理
核心原则：重构 ≠ 重写；保持接口兼容；有测试才重构；最小改动
参考文档：基于 vllm-ascend 仓库 20+ 个真实重构 PR 提炼
约束配置：所有数值阈值（函数行数、参数个数等）集中在
```
refactoring-config.json
```
，用户可自定义或禁用

Applicable Scenarios: Code refactoring, code review, code quality improvement, technical debt cleanup
Core Principles: Refactoring ≠ Rewriting; Keep interface compatibility; Refactor only with tests; Minimal changes
Reference Documents: Extracted from 20+ real refactoring PRs in the vllm-ascend repository
Constraint Configuration: All numerical thresholds (function lines, parameter count, etc.) are centralized in
```
refactoring-config.json
```
, which users can customize or disable

Quick Reference

任务	参考文档
自定义约束阈值	refactoring-config.json
识别代码问题	references/code-smells.md
选择设计模式	references/design-patterns.md
改善可读性	references/readability.md
实战模式与案例	references/refactoring-in-practice.md
生成重构文档	references/refactoring-report.md

Task	Reference Document
Customize constraint thresholds	refactoring-config.json
Identify code issues	references/code-smells.md
Select design patterns	references/design-patterns.md
Improve readability	references/readability.md
Practical patterns and cases	references/refactoring-in-practice.md
Generate refactoring documents	references/refactoring-report.md

坏味道 → 重构模式速查表

Code Smell → Refactoring Pattern Cheat Sheet

发现问题后，用此表快速定位解决方案：

坏味道	推荐模式	详细参考
过长函数	Extract Method、Guard Clause	code-smells.md §1.1
过长参数列表	dataclass 参数对象、Builder	design-patterns.md §1.3
重复代码（横切关注点）	装饰器模式	design-patterns.md §2.1
重复代码（流程骨架相同）	模板方法 / 策略模式	practice §模式三
上帝类	按职责拆分、组合替代继承	practice §模式二、五
过度继承	组合 + Protocol	design-patterns.md §3.1
if-elif 创建实例	工厂模式（注册表）	practice §模式一
if-elif 类型分发	多态 / singledispatch	design-patterns.md §3.4
多个 `xxx_with_yyy` 函数变体	策略模式（Protocol）	practice §模式三
dict/tuple 传递复合数据	dataclass 类型形式化	practice §模式七
魔法数字/字符串	枚举（Enum / IntEnum）	code-smells.md §3.3
自定义实现与上游重复	对齐上游 / 继承基类	practice §模式四
过大模块（>500 行）	分离关注点、包化	practice §模式二
基准测试证明的劣势路径	删除死路径	practice §模式六

After identifying issues, use this table to quickly locate solutions:

Code Smell	Recommended Pattern	Detailed Reference
Long Function	Extract Method, Guard Clause	code-smells.md §1.1
Long Parameter List	dataclass Parameter Object, Builder	design-patterns.md §1.3
Duplicate Code (Cross-cutting Concerns)	Decorator Pattern	design-patterns.md §2.1
Duplicate Code (Same Process Skeleton)	Template Method / Strategy Pattern	practice §Pattern 3
God Class	Split by Responsibility, Composition over Inheritance	practice §Pattern 2, 5
Excessive Inheritance	Composition + Protocol	design-patterns.md §3.1
if-elif Instance Creation	Factory Pattern (Registry)	practice §Pattern 1
if-elif Type Dispatch	Polymorphism / singledispatch	design-patterns.md §3.4
Multiple `xxx_with_yyy` Function Variants	Strategy Pattern (Protocol)	practice §Pattern 3
dict/tuple for Composite Data Transfer	dataclass Type Formalization	practice §Pattern 7
Magic Numbers/Strings	Enumeration (Enum / IntEnum)	code-smells.md §3.3
Custom Implementation Duplicating Upstream	Align with Upstream / Inherit Base Class	practice §Pattern 4
Oversized Module (>500 lines)	Separate Concerns, Package化	practice §Pattern 2
Disadvantaged Path Proven by Benchmark	Delete Dead Path	practice §Pattern 6

重构执行流程

Refactoring Execution Process

┌─────────────────────────────────────────────────────────┐
│  0. 前置检查                                              │
│     - 确认有测试覆盖（无则先补关键路径测试）                  │
│     - 确认代码可正常运行                                    │
│     - 评估重构规模 → refactoring-in-practice.md 规模矩阵   │
├─────────────────────────────────────────────────────────┤
│  1. 识别问题  →  references/code-smells.md               │
│     - 通读代码，按分类逐项检查                               │
│     - 输出问题清单，按严重程度排序                            │
├─────────────────────────────────────────────────────────┤
│  2. 选择策略  →  references/refactoring-in-practice.md   │
│     - 匹配七大实战模式，选择最合适的重构路径                  │
│     - 大型重构制定分阶段计划（参考 Quantization/MoE 案例）    │
├─────────────────────────────────────────────────────────┤
│  3. 结构重构  →  references/design-patterns.md           │
│     - 对结构性问题选择合适的模式                             │
│     - 实施重构，确保接口兼容                                 │
├─────────────────────────────────────────────────────────┤
│  4. 打磨优化  →  references/readability.md               │
│     - 改善命名、结构、类型标注                               │
│     - 补充必要注释和文档                                    │
├─────────────────────────────────────────────────────────┤
│  5. 验证                                                 │
│     - 运行全部已有测试，确认无回归                            │
│     - 运行 linter / type checker                          │
│     - 对比重构前后，确认行为一致                             │
├─────────────────────────────────────────────────────────┤
│  6. 输出重构文档（可选，用户请求时生成）                       │
│     - 汇总本次重构的完整记录                                 │
│     - 生成结构化文档，可用于 PR 描述 / 团队分享 / 项目归档     │
│     - 参见 references/refactoring-report.md                  │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  0. Pre-check                                              │
│     - Confirm test coverage (add critical path tests first if none)                  │
│     - Confirm code runs normally                                    │
│     - Evaluate refactoring scale → refactoring-in-practice.md Scale Matrix   │
├─────────────────────────────────────────────────────────┤
│  1. Identify Issues  →  references/code-smells.md               │
│     - Read through code, check item by item by category                               │
│     - Output issue list, sorted by severity                            │
├─────────────────────────────────────────────────────────┤
│  2. Select Strategy  →  references/refactoring-in-practice.md   │
│     - Match seven practical patterns, choose the most suitable refactoring path                  │
│     - Develop phased plan for large-scale refactoring (refer to Quantization/MoE cases)    │
├─────────────────────────────────────────────────────────┤
│  3. Structural Refactoring  →  references/design-patterns.md           │
│     - Select appropriate pattern for structural issues                             │
│     - Implement refactoring, ensure interface compatibility                                 │
├─────────────────────────────────────────────────────────┤
│  4. Polish and Optimize  →  references/readability.md               │
│     - Improve naming, structure, type annotations                               │
│     - Add necessary comments and documentation                                    │
├─────────────────────────────────────────────────────────┤
│  5. Validation                                                 │
│     - Run all existing tests, confirm no regression                            │
│     - Run linter / type checker                          │
│     - Compare before and after refactoring, confirm consistent behavior                             │
├─────────────────────────────────────────────────────────┤
│  6. Output Refactoring Document (optional, generated when requested by user)                       │
│     - Summarize complete record of this refactoring                                 │
│     - Generate structured document, usable for PR description / team sharing / project archiving     │
│     - See references/refactoring-report.md                  │
└─────────────────────────────────────────────────────────┘

重构决策指南

Refactoring Decision Guide

何时重构

When to Refactor

添加新功能前，先重构相关代码使其易于扩展
修复 Bug 时，顺便改善周边代码结构
Code Review 中发现的问题
代码难以理解或修改时

Before adding new features, refactor related code to make it easy to extend
When fixing bugs, improve the structure of surrounding code by the way
Issues found in Code Review
When code is difficult to understand or modify

何时不重构

When Not to Refactor

即将废弃的代码
没有测试覆盖且无法快速补充测试的核心代码
时间紧迫的紧急修复（先修复，后重构）
代码虽不完美但足够清晰且稳定运行

Code to be deprecated soon
Core code without test coverage and unable to quickly add tests
Urgent fixes with tight deadlines (fix first, refactor later)
Code that is not perfect but clear enough and runs stably

重构粒度控制

Refactoring Granularity Control

规模	范围	建议	参考案例
小型	单个函数/方法	直接修改，单次提交	MoE #5189 复用上游 all_reduce（-38 行）
中型	单个类或模块	拆分为 2-3 次提交	MoE #5481 dict/tuple → dataclass（6 文件）
大型	跨模块/包	制定计划，分阶段执行	Quantization 4 阶段重构（36 文件）

Scale	Scope	Recommendations	Reference Case
Small	Single function/method	Modify directly, submit in one commit	MoE #5189 Reuse upstream all_reduce (-38 lines)
Medium	Single class or module	Split into 2-3 commits	MoE #5481 dict/tuple → dataclass (6 files)
Large	Cross-module/package	Develop a plan, execute in phases	Quantization 4-phase refactoring (36 files)

重构文档模板

Refactoring Document Template

当用户请求生成重构文档（如 "输出重构文档"、"生成重构报告"、"写重构总结"）时，在重构完成并验证后，按 references/refactoring-report.md 中的模板生成文档。

文档支持按用途裁剪（PR 描述 / 团队分享 / 项目归档），小型重构可使用精简格式。详见参考文档。

When users request to generate refactoring documents (such as "output refactoring document", "generate refactoring report", "write refactoring summary"), after refactoring is completed and validated, generate documents according to the template in references/refactoring-report.md.

Documents can be tailored by purpose (PR description / team sharing / project archiving), and a simplified format can be used for small-scale refactoring. See reference documents for details.

输出格式

Output Format

对每个重构建议，按以下格式输出：

undefined

For each refactoring suggestion, output in the following format:

undefined

[问题类型] 问题简述

[Issue Type] Issue Brief

位置：

file_path:line_number

问题： 描述当前代码的问题 方案： 描述修复方案 实战参考： 匹配的实战模式（如适用） 修复前： （代码片段） 修复后： （代码片段） 依据： 引用的参考文档和具体规则

---

Location:

file_path:line_number

Issue: Describe the current code issue Solution: Describe the fix plan Practical Reference: Matching practical pattern (if applicable) Before Fix: (code snippet) After Fix: (code snippet) Basis: Cited reference documents and specific rules

---

References

详细参考文档：

code-smells.md — 代码坏味道识别与修复（函数/类/逻辑/模块四个层级，含 isinstance 链分发）
design-patterns.md — Pythonic 设计模式应用（创建型/结构型/行为型 + singledispatch + 反模式警示）
readability.md — 可读性与可维护性改进（命名/结构/类型标注/注释/模块组织/Pythonic 惯用法）
refactoring-in-practice.md — 基于 vllm-ascend 真实 PR 的重构实战经验（七大模式 + 安全守则 + 规模评估矩阵）
refactoring-report.md — 重构文档生成（模板 + 各节填写指南 + 场景适配 + 小型重构精简格式）

Detailed reference documents:

code-smells.md — Code smell identification and repair (four levels: function/class/logic/module, including isinstance chain dispatch)
design-patterns.md — Pythonic design pattern application (creational/structural/behavioral + singledispatch + anti-pattern warnings)
readability.md — Readability and maintainability improvement (naming/structure/type annotations/comments/module organization/Pythonic idioms)
refactoring-in-practice.md — Refactoring practical experience based on real vllm-ascend PRs (seven patterns + safety guidelines + scale evaluation matrix)
refactoring-report.md — Refactoring document generation (template + section filling guidelines + scenario adaptation + simplified format for small refactoring)

python-refactoring

Original

Translation

Python 代码重构

Python Code Refactoring

Overview

Overview

Quick Reference

Quick Reference

坏味道 → 重构模式 速查表

Code Smell → Refactoring Pattern Cheat Sheet

重构执行流程

Refactoring Execution Process

重构决策指南

Refactoring Decision Guide

何时重构

When to Refactor

何时不重构

When Not to Refactor

重构粒度控制

Refactoring Granularity Control

重构文档模板

Refactoring Document Template

输出格式

Output Format

[问题类型] 问题简述

[Issue Type] Issue Brief

References

References

坏味道 → 重构模式速查表