Python项目可维护性核心在于组织逻辑而非仅格式规范：按业务域划分包结构、命名体现上下文、测试与配置一等地位。
Python项目要写得清晰、易读、好维护，遵守PEP 8是基础，但光缩进对齐、空格换行还不够——真正影响长期可维护性的，是代码组织方式、模块职责划分和命名背后的一致逻辑。
PEP 8不是“格式检查清单”，而是可读性契约
PEP 8的核心目标不是统一风格，而是降低他人（包括未来的你）理解代码的认知负担。比如：
- 函数名用snake_case，类名用PascalCase，不只是为了好看，而是让读者一眼分辨出“这是行为”还是“这是实体”
- 每行不超过79字符，本质是避免横向滚动和侧头阅读，尤其在并排查看diff或多人协作时更友好
- 导入语句分三组（标准库 / 第三方库 / 本地模块），且每组内按字母排序，是为了快速定位依赖来源，而不是靠记忆猜模块在哪
模块与包结构要反映业务边界，而非技术分层
常见误区是照搬Java式分层（models/、views/、utils/），结果导致业务逻辑散落在各层、修改一个功能要跳转五六个文件。更可持续的做法是：
- 按业务能力或领域概念组织顶层包，例如orders/、payments/、notifications/
- 每个业务包内再按关注点分离：如orders/models.py、orders/services.py、orders/api.py，但不强行拆出orders/utils.py——工具函数应优先放在最靠近使用处的模块里
- 顶层__init__.py只暴露稳定接口，隐藏内部实现细节，例如from .services import create_order，而非from .models import Order
命名即文档：变量、函数、模块名必须携带足够上下文
短名（如obj、data、res）看似省事，实则每次阅读都要回溯推断含义。好名字应该回答三个问题：它是什么？它属于谁？它用来做什么？
立即学习“Python免费学习笔记（深入）”；
- 避免def process():，改用def calculate_order_total():
- 避免user_data = fetch(...)，改用active_user_profile = fetch_user_profile(user_id)
- 模块名不加_module或_util后缀，email_sender.py比email_utils.py更能说明职责
测试与配置不是附属品，它们该有自己的一等地位
把测试文件丢进tests/根目录、配置硬编码在settings.py里，会拖慢迭代节奏。合理做法是：
- 测试与被测模块同级，用test_*.py命名，例如orders/test_services.py对应orders/services.py，IDE和pytest能自动发现并聚焦
- 配置按环境分层：config/base.py定义通用项，config/dev.py和config/prod.py只覆盖差异字段，启动时通过环境变量加载
- 敏感配置（密钥、地址）绝不提交，用pydantic-settings或environs从环境变量或.env文件加载，本地开发用dotenv支持
