Ascend/python-refactoring

Python 代码重构

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

Overview

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

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 |

---

坏味道 → 重构模式 速查表

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

| 坏味道 | 推荐模式 | 详细参考 | |--------|----------|----------| | 过长函数 | 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 §模式六 |

---

重构执行流程

┌─────────────────────────────────────────────────────────┐
│  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                  │
└─────────────────────────────────────────────────────────┘

---

重构决策指南

何时重构

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

何时不重构

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

重构粒度控制

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

---

重构文档模板

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

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

---

输出格式

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

### [问题类型] 问题简述

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

---

References

详细参考文档：

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