17370845950

可维护性源于日常习惯：用动宾函数名、提取中间变量、避免深层嵌套；显式声明边界假设；添加类型提示；以测试驱动设计；隔离易变逻辑。

写 Python 代码不难，难的是半年后你、同事或新来的同学还能轻松看懂、安全修改、快速扩展。长期可维护性不是靠“以后再重构”，而是从第一行函数开始就埋下的习惯。

用明确意图替代聪明写法

可读性是可维护性的地基。Python 的“优雅”常被误解为“短”或“一行解决”。但 让别人一眼看出你“想做什么”，比“你怎么做到的”重要得多。

✅ 好做法：

• 函数名用动宾结构：validate_email_format

  

  比 check_str 清晰十倍
• 提取中间变量说明用途：is_legacy_user = user.created_at ，而不是直接塞进 if 条件里
• 避免嵌套过深：三层以上 if/for 就该拆成小函数，哪怕只调用一次

把边界和假设“写进代码里”

很多 bug 和后续返工，源于隐含假设没暴露——比如“这个列表永远不为空”“API 返回字段一定存在”“时区默认是 UTC”。这些不该靠注释提醒，而要靠代码主动声明。

✅ 好做法：

• 用 assert 或自定义校验函数守住关键契约：assert len(items) > 0, "Expected at least one item"
• 字典取值不用 d['key']，改用 d.get('key', default) 或 d.get('key') is not None 显式处理缺失
• 类型提示不只是给 IDE 看的：def process_orders(orders: list[Order]) -> dict[str, float]: 是接口契约，也是文档

让测试成为“设计说明书”而非“验收补丁”

写测试不是为了凑覆盖率数字，而是逼自己把模块职责想清楚：它接收什么？保证输出什么？哪些情况必须失败？

✅ 好做法：

• 每个函数/类的单元测试，先写“正常路径”，再写 2–3 个典型异常路径（空输入、非法参数、外部依赖失败）
• 测试名直说行为：test_calculate_discount_applies_10_percent_for_vip_users，比 test_case_1 有用得多
• 用 pytest.mark.parametrize 把边界值集中表达，比如测试不同长度字符串、负数、None 等

把“变化点”隔离出来，别让它到处长根

业务逻辑总在变：折扣规则改了、第三方 API 升级了、数据库加了字段……如果这些变化散落在 5 个文件、8 个函数里，维护就是灾难。

✅ 好做法：

• 把易变逻辑抽成独立模块或配置：折扣策略 → discount_strategies.py；API 地址/超时 → settings.py 或环境变量
• 用依赖注入代替硬编码：函数接受一个 email_sender 对象，而不是直接调用 smtplib.send()
• 对外部服务封装薄层适配器（Adapter），内部只跟适配器交互——换服务商时只改一层，不影响业务逻辑

不复杂但容易忽略：可维护性不是某个阶段的任务，它是每次 git commit 时，你多花 30 秒命名变量、加一行类型提示、拆出一个小函数所累积出来的结果。