命名和结构设计是提升 Python 代码可读性的两个最直接、最有效的切入点：变量函数名用完整单词表达意图，类模块名反映职责边界，函数应小而专注、输入输出明确，目录按业务域而非技术类型组织。
命名和结构设计是提升 Python代码可读性 的两个最直接、最有效的切入点。好名字让意图一目了然，合理结构让逻辑层层分明——不需要注释就能看懂“在做什么”和“为什么 这么做”。
变量与函数名：用完整单词表达意图
避免缩写（除非是广泛接受的，如red”>id、url）、单字母（如x、l）或模糊词（如data、info）。名称应体现其用途或业务含义。
- user_input 比 inp 更清晰；
- calculate_total_discount 比 calc 更明确；
- is_eligible_for_promotion 比 check_flag 更具语义。
类与模块名：反映职责边界
类名用 PascalCase，准确概括其核心职责；模块名用 snake_case，聚焦单一主题。一个模块不应同时处理用户认证、订单生成和日志上报——拆分后更易定位、测试和复用。
- 把 utils.py 按功能重命名为auth_helpers.py、order_validators.py；
- 类 PaymentProcessor 比Handler更能说明它“负责支付流程的执行与状态管理”；
- 避免“上帝类”，比如 SystemManager，应拆为UserManager、ConfigLoader 等。
函数结构：小而专注，输入输出明确
单个函数只做一件事，长度控制在 20 行以内（不含空行和注释），参数不超过 4 个。复杂逻辑应拆解为多个小函数，并通过函数名传递意图。
立即学习“Python 免费学习笔记（深入）”；
- 把长函数 process_order() 拆成validate_order()、reserve_inventory()、charge_payment()；
- 用 return 提前结束代替深层嵌套，减少缩进层级；
- 避免修改传入的可变对象（如 list/dict），如需变更，显式复制或注明inplace=True。
目录与文件组织：按领域分层，而非技术类型
别再用 models/、views/、controllers/ 机械划分。按业务域组织（如auth/、billing/、notifications/），每个子目录内再按角色组织文件，保持上下文集中。
- auth/下包含models.py、services.py、api.py，而不是把所有 model 塞进顶层models/；
- 共用 工具 放在 shared/ 或core/，但要限制其增长，优先考虑领域内复用；
- 测试文件与被测代码同级（如 billing/charge.py 对应billing/test_charge.py），便于查找和维护。
