写代码就像写文章，除了要把事做对，还要让读的人看得舒服。在 Python 生态里，PEP 8 是公认的编码风格指南，团队成员遵循同一套规范，代码评审时就不用争论格式问题，精力可以全放在逻辑上。
PEP 8 核心要点
PEP 8 覆盖很多细节，日常开发中记住下面这几条就能覆盖 90% 的场景：
缩进与空格
- 使用 4 个空格 缩进，不准混用 Tab。
- 每行代码长度不超过 79 个字符（文档字符串不超过 72 个字符）。现在屏幕大了，团队内约定 119 字符也是常见做法，但 79 是多窗口并排阅读的经典值。
- 顶层函数和类定义之间用 两个空行 隔开；类内方法定义之间用 一个空行 隔开。
- 二元运算符前后、逗号后面各加一个空格，但括号内侧不加空格。
导入规范
- 每个导入独占一行：
import osimport sys，不要import os, sys。 - 导入位于文件顶部，分三组顺序，每组间空一行：标准库 → 第三方库 → 本地模块。
- 避免使用
from module import *，它会污染命名空间，让你不知道名字从哪来。
括号与换行
- 长表达式可以用括号隐式续行，推荐把运算符放在行首以提高可读性。
- 函数参数太多时，参数可以分行写，对齐或悬挂缩进。
其他习惯
- 单例比较用
is/is not而不是==（如if x is None）。 - 判断序列是否为空用
if not seq:而不是if len(seq) == 0。 - 不要行尾留空白，文件末尾留一个换行符。
命名规范
命名是代码可读性的第一关，PEP 8 给出了清晰的命名约定：
| 类型 | 命名规则 | 示例 |
|------------------------|-------------------------------------|-----------------------------|
| 模块名、包名 | 小写字母，可用下划线，简短为主 | utils.py, data_loader |
| 类名、异常名 | 首字母大写的驼峰体（CapWords） | UserProfile, HttpError |
| 函数名、方法名、变量名 | 小写字母，单词间用下划线分隔 | get_user, total_count |
| 常量 | 大写字母，单词间用下划线分隔 | MAX_SIZE, DEFAULT_HOST |
| 私有属性/方法 | 单下划线开头（内部使用约定） | _cache, _internal_func |
| 名称修饰（避免子类覆盖）| 双下划线开头（非双下划线结尾） | __private_method |
| 特殊方法（魔法方法） | 双下划线开头和结尾 | init, str |
要点：
- 命名要见名知意，用能准确描述用途的词，避免单字母变量（除循环中的
i,j等）。 - 不用拼音，不用中文，用常见英文缩写即可。
- 布尔变量前缀
is_或has_，如is_active。
注释规范
注释不是给代码“配音”，而是解释“为什么这样做”。好的注释减少理解成本，过时或错误的注释比没有更糟。
基本原则
- 保持注释与代码同步更新，修改代码时必须同步修正注释。
- 清晰说明意图和背景，不要复述代码：
x = x + 1 # 将 x 增加 1是典型的废话注释。 - 用完整句子，英文注释首字母大写，中文注释使用主谓宾结构。
几种注释形式
- 块注释：用于解释整段逻辑。每行以
#开头，后跟一个空格。 - 行内注释：放在语句后面，与代码至少间隔两个空格。尽量少用，只有真正需要额外说明时才加。
- 文档字符串（docstring）：为模块、类、函数编写描述，写在定义体的第一行。单行文档字符串用三次双引号，多行时第一行概述，空一行后详细描述。这是自动生成文档的重要原材料。
编写建议
- 公共函数和类必须写文档字符串，说明功能、参数、返回值、可能抛出的异常。
- 复杂算法或特殊处理逻辑，在关键步骤前加入简洁注释，说明“为什么这样处理”。
- 避免注释嵌套、长篇大论，把长段注释变成文档字符串更好。
遵守这些规范，配合代码格式化工具（下一节会讲到 Black、isort 等），可以大幅降低项目协作的沟通成本，也让你的代码看起来更专业可靠。