Python代码审查要点_质量把控说明【指导】

Python代码审查是保障可维护性、可读性和健壮性的协作过程，核心聚焦命名清晰性、函数单一职责、异常处理合理性、依赖可测试性四大高频要点。

Python代码审查不是挑错，而是保障可维护性、可读性和健壮性的协作过程。核心目标是让代码“别人能看懂、改得动、跑得稳”。以下是从实践中提炼的高频审查要点，聚焦真实开发场景中的关键风险。

命名是否清晰表达意图

变量、函数、类名应直接反映其用途，避免缩写歧义或过度泛化。

• ✅ 推荐：user_profile_data、calculate_discounted_price()、PaymentProcessor
• ❌ 避免：data、func1()、obj、get_info()（没说明是什么的info）
• 特别注意布尔变量：用 is_active、has_permission 而非 active_flag 或 permission

函数是否单一职责且边界明确

一个函数只做一件事，并能通过名字和参数预判行为范围。

• 检查是否混杂I/O、计算、状态修改；例如：一边读文件、一边处理数据、一边写日志——应拆分为 load_config()、validate_config()、log_config_load()
• 参数超过4个需警惕，考虑封装为数据类（dataclass）或字典传入
• 避免函数内含多层嵌套条件（如 if → for → if），优先用卫语句（guard clause）提前返回

异常处理是否合理而非掩盖问题

不捕获所有异常（except:），也不忽略错误细节；要区分“可恢复”与“应中断”的场景。

• ✅ 合理：except FileNotFoundError 处理缺失配置文件，提供默认值或提示
• ❌ 危险：except Exception as e: pass 或仅打印 e 而不记录上下文
• 建议：使用 logging.exception() 记录完整堆栈；业务异常（如余额不足）应抛出自定义异常，便于上层统一响应

依赖与可测试性是否被忽视

硬编码路径、全局状态、未抽象的外部调用，都会阻碍单元测试和后续重构。

• 检查是否有 open('/tmp/log.txt')、requests.get('https://api.example.com') 等直连逻辑——应通过参数注入或接口抽象
• 函数是否依赖模块级变量或单例？尝试在测试中重置/替换它们是否可行？
• 有无隐藏副作用？例如修改传入的 list/dict 参数，却未在文档或类型注解中声明

代码审查不是追求完美语法，而是守住团队协作的底线。每次合并前花10分钟对照这几条快速过一遍，能显著降低后期排查成本。