28 lines
1021 B
Markdown
28 lines
1021 B
Markdown
# 代码质量（Code Quality）
|
||
|
||
本文件定义代理对代码质量的最低要求与审查清单（Python）。
|
||
|
||
## 1. 总体要求
|
||
|
||
- 改动聚焦目标；避免“顺手重构”。
|
||
- API/行为变更要显式说明影响与迁移方式（尤其是脚本/CLI 输出与配置项）。
|
||
- 保持仓库现有约定：优先复用既有结构、命名与工具配置（见 `docs/python/`）。
|
||
|
||
## 2. 可读性
|
||
|
||
- 复杂逻辑拆分为具名函数/模块；避免超长函数。
|
||
- 尽量使用显式类型与数据结构表达意图（必要时补类型标注）。
|
||
- 注释解释“为什么”，避免注释重复代码表述。
|
||
|
||
## 3. 错误处理
|
||
|
||
- 失败必须可观测：返回码/异常/日志至少一种要明确。
|
||
- CLI/自动化脚本：遇到不可恢复错误应非零退出码。
|
||
|
||
## 4. Review 清单
|
||
|
||
- 是否引入了不必要的新依赖？
|
||
- 是否遵循 `pyproject.toml` 与 lint 配置？
|
||
- 是否对 I/O（文件/网络/数据库）失败路径做了处理？
|
||
- 是否需要补测试或示例？
|