Python 可维护代码的表达原则

代码可维护性取决于命名准确性、参数精简（≤5个，多则封装）、控制流扁平（嵌套≤3层，用卫语句/生成器）、边界测试全覆盖（空值/零值/极值）及意图明确的布尔变量。

函数别超过 5 个参数

参数一多，调用时容易传错顺序、漏传、搞混含义，而且加新参数会破坏所有调用点。不是不能超，而是超过就得立刻考虑拆分或封装。

• 用 dataclass 或 TypedDict 封装相关参数，比如把 user_id, name, email, is_active, created_at 收进一个 UserInput 类里
• 位置参数（*args）和关键字参数（**kwargs）看着灵活，但会隐藏接口契约，别人看调用点根本不知道该传啥
• ide 和类型检查器（如 mypy）对长参数列表的提示效果明显下降，def send_email(to, subject, body, cc, bcc, reply_to, timeout, retries) 这种函数，光靠签名几乎无法安全使用

避免嵌套超过 3 层的 if/for/try

嵌套深了，逻辑就藏在缩进里，读代码像下楼梯——每层都得记住上一层的条件，稍不注意就漏掉 else 分支或提前 return 的边界。

• 用卫语句（guard clause）提前退出：把 if not valid: return 放最前面，而不是包在大 if 里
• for 嵌套超过两层？大概率该抽成生成器函数，比如 for user in users: → for order in get_orders_by_user(user):
• try/except 嵌套常见于“先试 A，失败再试 B”，这时更适合用 except 后跟多个异常类型，或把重试逻辑放进单独函数，而不是层层套 try

变量名必须能回答“它现在代表什么”

不是“有没有类型注解”，而是人扫一眼就得知道这个变量在当前上下文里承担什么角色。类型注解是辅助，不是替代。

• 别用 data、info、temp 这类万金油名字；user_profile_json 比 data 好，normalized_user_profile 比 user_profile_json 更准——它说明了状态和意图
• 布尔变量必须是可读的谓词：is_expired、has_unsaved_changes，而不是 flag1 或 valid（valid 是谁 valid？对谁 valid？）
• 循环变量别图省事写 i、x；for config_file in config_files: 比 for f in files: 更不容易误用，尤其当循环体里还有子循环时

测试用例必须覆盖边界值和空输入

可维护性差的代码，往往不是功能写错了，而是没处理好“没有东西”的情况——空列表、None、空字符串、零值、空字典。这些不是边缘 case，是日常输入。

立即学习“Python免费学习笔记（深入）”；

• 每个函数只要接受可为空的参数（比如 Optional[str]），测试里就得有 None 输入的用例，且明确断言行为（抛异常？返回默认值？静默跳过？）
• 处理列表的函数，至少测三种长度：0、1、≥2；别只用 [1, 2, 3] 模拟“正常情况”
• 用 pytest.mark.parametrize 把边界值列清楚，比写一堆独立 test_ 函数更易维护，也更容易发现漏掉的分支

最难的不是写出能跑的代码，是让三个月后的自己或新同事，不用翻三页上下文就能看懂某行 user_map[uid].status = 'archived' 为什么在这里改、会不会影响其他地方。可维护性藏在命名选择、参数粒度、控制流扁平度这些每天敲键盘时的微小决定里。