Python Code Review — 代码质量审查

对 Python 代码进行系统化质量审查，按照以下 8 个维度逐项检查并给出可执行的改进建议。

Read references/python-style-guide.md now and use it as the authoritative reference for Python conventions throughout this review.

审查流程

对每个被审查的文件，按顺序完成以下 8 个维度的检查。每个维度完成后用 ✅ / ⚠️ / ❌ 标注结果。

1. 命名规范 (Naming)

• 变量/函数名是否使用 snake_case？类名是否使用 PascalCase？常量是否使用 UPPER_SNAKE_CASE？
• 名称是否语义清晰、长度适中？（避免 x, df, tmp, data 等无意义变量名）
• 布尔变量是否以 is_ / has_ / should_ / can_ 开头？
• 私有成员是否以单下划线 _ 开头？内部私有是否以双下划线 __ 开头？
• 避免与 Python 内置名称冲突（list, dict, id, type, str 等）

2. 函数/方法设计 (Function Design)

• 函数是否遵循单一职责原则？一个函数只做一件事？
• 函数长度是否合理？（超过 50 行建议拆分，超过 100 行强烈建议重构）
• 参数数量是否过多？（超过 5 个建议使用 dataclass/TypedDict/dict 封装）
• 是否有过多的布尔标志参数？（考虑拆成两个函数或用 enum）
• 函数是否有明确的返回值？避免返回多种不兼容类型

3. 复杂度与可读性 (Complexity)

• 嵌套层级是否过深？（超过 3 层建议提取函数或用 early return 扁平化）
• 条件分支是否过多？（超过 4 个 elif 考虑用 dict 映射或 match-case）
• 列表推导式是否过于复杂？（超过一层嵌套的推导式改用普通循环）
• 是否有"神奇数字"？（用命名常量替代，如 MAX_RETRIES = 3）
• 是否有重复代码块？（DRY 原则，提取为函数或装饰器）

4. 类型安全 (Type Safety)

• 是否使用了类型注解？（函数签名、类属性、复杂数据结构）
• 类型注解是否准确？（避免 Any，用 Protocol / TypeVar / Union 替代）
• 是否能通过 mypy --strict 检查？
• 是否合理使用了 Optional / Union / Literal / Final？

5. 异常处理 (Error Handling)

• 是否使用了裸露的 except: 或 except Exception: pass？（禁止吞掉异常）
• 异常捕获范围是否过于宽泛？（应捕获具体异常类型）
• 是否有正确的资源清理？（使用 with 语句管理文件/连接/锁）
• 自定义异常是否继承自合适的基类？（至少 Exception，非 BaseException）
• 关键操作失败时是否有清晰的错误信息？

6. Docstring 与注释 (Documentation)

• 公共函数/类是否有 docstring？（遵循 Google 或 NumPy 风格）
• docstring 是否描述了参数、返回值、异常？
• 注释是否解释了"为什么"而非"做什么"？（好的代码自解释"做什么"）
• 是否有过时或误导性的注释？
• 是否有被注释掉的代码块？（应删除，用 git history 追溯）

7. 安全性 (Security)

• 是否有硬编码的密钥/密码/Token？
• 用户输入是否经过验证和清理？
• 文件路径是否安全？（防范路径遍历攻击）
• SQL 查询是否使用参数化查询？
• eval() / exec() / os.system() 是否必要且安全？
• pickle/unpickle 是否用于不可信数据？

8. 性能与最佳实践 (Performance)

• 循环中是否有不必要的重复计算？（提取到循环外）
• 是否使用了合适的容器？（set 做成员检查，deque 做队列，defaultdict 做分组）
• 字符串拼接是否用 join() 而非循环 +=？
• 是否滥用全局变量或可变默认参数？
• 文件/网络/数据库连接是否正确关闭和复用？
• import 是否有未使用的模块？是否使用了 import *？

输出格式

审查完成后，按以下格式输出报告：

## Code Review Report — {文件名或 PR 标题}

### 概览
- 审查文件数: N
- 严重问题: N | 警告: N | 建议: N

### 严重问题 (必须修复)
| 行号 | 维度 | 问题 | 修复建议 |
|------|------|------|----------|

### 警告 (建议修复)
| 行号 | 维度 | 问题 | 修复建议 |
|------|------|------|----------|

### 优化建议 (可选)
| 行号 | 维度 | 问题 | 修复建议 |
|------|------|------|----------|

### 亮点
- 值得肯定的代码片段

### 总结
一段话总结整体质量水平和最关键的改进方向。

评分标准