代码可维护性取决于命名准确性、参数精简（≤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' 为什么在这里改、会不会影响其他地方。可维护性藏在命名选择、参数粒度、控制流扁平度这些每天敲键盘时的微小决定里。
