写可维护的 Python 代码，核心不是“多炫技”，而是让别人（包括未来的你）能快速看懂、安全修改、轻松扩展。这靠的是规范打底、重构护航、习惯支撑。
用 PEP 8 打好基础，不靠感觉靠标准
PEP 8 是 Python 官方风格指南，不是可选项，是协作底线。它解决的不是“好不好看”，而是“读得快不快、改得稳不稳”。
-
命名清晰直白：用
user_profile不用up或usr_prf；函数名用calculate_total_price()而非calc()—— 名字本身要传递意图。 -
空格与换行讲逻辑：逗号后加空格，二元运算符两侧加空格（
a = b + c），函数参数过长就换行并缩进对齐，不是为了“省行数”，是为了眼睛能自然分组。 -
单行别塞太多事：避免
if x and y or z: do_a(); do_b(); return c这类“一行三件事”。拆开，每行一个动作，出问题时堆栈更准，调试更省力。
函数要小、职责要纯、接口要稳
一个函数只做一件事，而且把这件事做好。这是降低认知负担最有效的方式。
-
长度控制在 20 行内：超过多半说明职责混杂。比如一个“处理订单”的函数，如果又查库存、又发邮件、又更新数据库，就该拆成
check_stock()、send_confirmation_email()、update_order_status()。 -
参数不超过 3 个：多了就考虑封装成数据类（
dataclass）或字典传入。例如：
✅ 好：create_user(name="Alice", email="a@b.com", role="admin")
❌ 差：create_user("Alice", "a@b.com", "admin", True, None, "UTC+8", False)—— 顺序和含义全靠记。 -
避免副作用：函数尽量不偷偷改全局变量、不原地修改传入的 list/dict。需要修改？返回新对象，或明确用
inplace=True标识。
重构不是“重写”，是“小步验证的持续优化”
重构的时机不是等代码烂到没法改，而是每次动代码前、加功能时、甚至读到困惑处——只要测试能跑通，就值得优化一丁点。
立即学习“Python免费学习笔记（深入）”；
- 先补测试，再动手：哪怕只是 2 行单元测试，也能守住行为边界。没测试就重构，等于蒙眼开车。
-
常用安全手法：
- 提取函数（Extract Method）：重复逻辑、嵌套过深、注释成段的地方，直接剪出来命名。
- 合并条件（Consolidate Conditional Expression）：多个 if 判断同一变量，改用字典映射或 match-case（Python 3.10+）。
- 以多态替代条件（Replace Conditional with Polymorphism）：当 if/elif 按类型分支且越来越多，就该考虑抽象基类或策略模式。
- 警惕“技术债信号”：函数里出现 “TODO: refactor this” 却一直没动；同事 PR 评论里反复出现 “这里看不懂”；改一处 bug，另一处冒出来 —— 这些都是重构的明确指令。
文档与类型提示，是给机器和人共同写的说明书
注释不是越多越好，而是“不写注释也能说清时，就不写”。真正值得写的，是 Why，不是 What。
-
用 type hints 显式声明意图：写
def process_items(items: list[str]) -> dict[str, int]:，比写# items is a list of strings更可靠，IDE 能检查，mypy 能报错，别人一眼懂边界。 -
docstring 说清楚“为什么这么设计”：比如
"""Returns cached result if available; bypasses cache in test mode to ensure fresh data."""—— 这比“返回结果”有用十倍。 - README 和模块级 docstring 不可少：新同学克隆项目后，5 分钟内应能搞懂“这是干啥的、怎么跑起来、核心模块各管什么”。这不是附加工作，是降低团队启动成本的刚需。
