Python编码规范的核心目标是提升代码可读性与可维护性，通过命名清晰、空格缩进统一、函数模块职责单一、类型提示及精准注释等实践降低协作成本。
Python编码规范的核心目标是提升代码可读性，让他人（以及未来的你）能快速理解逻辑、定位问题、安全修改。这不只是“写得好看”，而是通过统一约定降低协作和维护成本。
命名清晰：用名字说清“它是什么”
变量、函数、类的名称应准确表达其用途或含义，避免缩写歧义或过度简写。
- 用lowercase_with_underscores命名变量和函数，如user_age、calculate_total_price
- 类名用CapWords（驼峰式），如DataProcessor、APIResponseHandler
- 常量全大写加下划线，如MAX_RETRY_ATTEMPTS、DEFAULT_TIMEOUT_SEC
- 避免单字母变量（除非在极短作用域，如循环索引i、j），不用tmp、data、info这类模糊词
空格与缩进：视觉节奏决定阅读效率
PEP 8明确要求4个空格缩进，不使用Tab；空格也用于分隔操作符和关键符号，增强语法结构的可辨识度。
- 二元运算符两侧加空格：x = a + b * 2，不是x=a+b*2
- 逗号、冒号、分号后加空格：func(name: str, age: int) -> None:
- 函数调用时括号内不紧贴参数：print("Hello", name)，而非print("Hello",name)
- 空行分隔逻辑段：函数之间空两行，方法之间空一行，类内逻辑块间可空一行
函数与模块职责单一
一个函数只做一件事，且把这件事做好。过长的函数（超过20–25行）、嵌套过深（>3层）或含多个return点，通常是拆分信号。
立即学习“Python免费学习笔记（深入）”；
- 函数长度控制在屏幕一屏内可见，便于整体把握流程
- 提取重复逻辑为独立函数，哪怕只调用两次——提升复用性与测试便利性
- 模块保持主题聚焦：比如utils/date.py只处理日期格式化/计算，不混入网络请求或日志功能
- 用类型提示明确接口契约：def parse_config(path: Path) -> dict[str, Any]:
注释与文档字符串：解释“为什么”，而非“做什么”
代码本身应尽量自解释；注释应补充上下文、权衡取舍或特殊原因，而不是翻译代码。
- 函数顶部用三重双引号写docstring，说明功能、参数、返回值、异常，如"""Calculate compound interest given principal, rate, and years."""
- 避免冗余注释：# increment i by 1 → i += 1 已足够清晰
- 关键算法、绕过bug的临时方案、性能敏感处必须注释原因，例如# Using float division here to match legacy API behavior (int division changed in v3.10)
- 行尾注释慎用；优先考虑重构为更清晰的变量名或函数
