可维护性源于日常习惯：用动宾函数名、提取中间变量、避免深层嵌套；显式声明边界假设；添加类型提示；以测试驱动设计；隔离易变逻辑。
写 Python 代码不难，难的是半年后你、同事或新来的同学还能轻松看懂、安全修改、快速扩展。长期可维护性不是靠“以后再重构”，而是从第一行函数开始就埋下的习惯。
用明确意图替代聪明写法
可读性是可维护性的地基。Python 的“优雅”常被误解为“短”或“一行解决”。但 让别人一眼看出你“想做什么”，比“你怎么做到的”重要得多。
✅ 好做法：
- 函数名用动宾结构：
validate_email_format比check_str清晰十倍 - 提取中间变量说明用途：
is_legacy_user = user.created_at ，而不是直接塞进 if 条件里 - 避免嵌套过深：三层以上 if/for 就该拆成小函数，哪怕只调用一次
把边界和假设“写进代码里”
很多 bug 和后续返工，源于隐含假设没暴露——比如“这个列表永远不为空”“API 返回字段一定存在”“时区默认是 UTC”。这些不该靠注释提醒，而要靠代码主动声明。
立即学习“Python免费学习笔记（深入）”；
✅ 好做法：
- 用
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 秒命名变量、加一行类型提示、拆出一个小函数所累积出来的结果。
