Python 代码可维护性需量化评估，重点关注圈复杂度（超 10 需拆分）、函数 / 类长度（函数≤30 行、类≤200 行）、嵌套层级（用卫语句降层）、重复代码与魔数（提取函数 / 常量 / 配置），并纳入 CI 静态分析。
Python 代码的复杂度和可维护性不是靠感觉判断的，而是有可量化的指标和明确的改进路径。关键在于关注函数长度、嵌套层级、圈复杂度、重复代码和命名一致性这几个核心维度。
圈复杂度（Cyclomatic Complexity）是首要关注点
它反映一个函数中独立执行路径的数量，直接影响测试难度和出错概率。值超过 10 通常意味着逻辑过重，需拆分。
- 用 radon 工具 快速检测：
radon cc your_module.py -a，查看每个函数的 CC 值 - if/elif/else 链、for/while 循环、逻辑运算符（and/or）、try/except 都会增加圈复杂度
- 典型优化：把长条件判断封装成独立函数；将异常处理逻辑提取为专用错误处理函数
函数与类不宜过长，单职责必须清晰
超过 30 行的函数、超过 200 行的类，往往承担了太多责任，阅读和修改成本陡增。
- 按功能切分：比如一个“生成报表”函数，可拆为
load_data()、validate_input()、render_html() - 避免“一函数多用途”：不把数据获取、格式转换、日志记录、返回响应全塞进一个 def 里
- 类应遵循单一职责原则——一个类只负责一种实体或行为，如
UserAuthenticator不处理邮件发送
减少嵌套层级，优先使用卫语句（Guard Clauses）
深度嵌套（如 if 内套 if 再套 for）会让逻辑难以跟踪，也容易遗漏边界情况处理。
立即学习“Python 免费学习笔记（深入）”；
- 用提前返回替代深层缩进：先检查非法输入并 return，而不是用大段 else 包住主逻辑
- 避免连续三层以上缩进；超过两层时，考虑提取子函数或使用策略模式
- 示例：把
if user and user.is_active and user.has_permission(): ……改为分步校验 + 早退
重复代码与魔数是可维护性的隐形杀手
相同逻辑在多个地方出现，改一处漏一处；硬 编码 的数字、字符串让意图模糊且难以统一更新。
- 识别重复：用duplication detector（如
pylint --enable=duplicate-code）扫描 - 提取为函数或常量：把
datetime.now() + timedelta(days=30)封装成get_expiration_date()，把200换成HTTP_STATUS_OK = 200 - 配置外移：数据库 URL、超时时间等不应写死在代码里，用 环境变量 或配置文件 管理
不复杂但容易忽略：定期运行静态分析（pylint、flake8、radon），把复杂度阈值写进 CI 流程，让问题在提交前暴露。可维护性不是写完才考虑的事，而是每行代码诞生时就该有的意识。
