PEP 8是Python协作基础设施，核心是可读性与工具链兼容；要求4空格缩进、snake_case命名函数变量、CapWords命名类、UPPER_SNAKE_CASE命名常量、每行≤79字符、合理空行及注释。
PEP 8 不是装饰，是协作基础设施
它直接决定你写的代码能不能被别人（包括三个月后的你自己）快速看懂。Python 没有花括号和类型声明，缩进、空格、命名这些“视觉线索”就是语法的一部分。一旦 class_name 和 ClassName 混用，或 def get_user() 和 def GetUser() 并存，IDE 的自动补全、grep 查找、git diff 对比都会变慢，甚至出错。
常见错误现象：
- 团队成员提交的代码在
black格式化后大量冲突，因为有人手动调了空格、有人用 Tab -
import os, sys, json写成一行，而另一个人拆成三行且顺序不一致，导致flake8报E402（import not at top of file） - 函数名用
parseData，但同模块里另一个函数叫format_user_info，阅读时无法靠命名快速区分职责
4 空格缩进不是审美选择，是解析器硬性依赖
Python 解析器把缩进当作语法结构标记。用 Tab 或混用空格，可能在不同编辑器里显示为 2 格或 8 格，但解释器只认实际字符——这会导致 IndentationError: unindent does not match any outer indentation level 这类报错，且极难定位。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在 VS Code / PyCharm 中关闭「Insert spaces when pressing Tab」选项，改用纯空格
- 配置编辑器保存时自动去除行尾空格（
files.trimTrailingWhitespace） - 在项目根目录加
.editorconfig，强制统一缩进规则，内容包含：indent_style = space、indent_size = 4
为什么 black 要比手写 PEP 8 更可靠
人工遵守 PEP 8 容易在细节上反复失守：行长判断、括号换行对齐、逗号后空格、运算符两侧空格……这些琐碎规则靠人盯效率低、易出错。black 是确定性格式化器，给定相同输入，永远输出唯一合法格式，消除了风格争论。
使用场景与参数差异：
- 默认行长 88 字符（非 PEP 8 的 79），更适配现代宽屏；可通过
--line-length 99调整 - 对类型提示、f-string、字典展开等新语法支持更及时，而手写容易遗漏
- 不支持配置“保留原有换行”，意味着你不能靠加空行来“强调逻辑分组”——这反而是好事：逻辑分组应靠函数拆分，而非空行堆砌
命名不规范会直接破坏工具链
静态分析、重构、文档生成这些自动化流程都依赖命名约定。比如 sphinx-autodoc 默认只提取 def 和 class 声明，但如果一个模块里混着 MyClass 和 my_class，生成的 API 文档就会语义混乱；pylint 会因 invalid-name 报一大堆警告，掩盖真正的问题。
关键边界：
-
_internal_var：表示模块级受保护，from module import *不会导入它 -
__private_method：名称改写（name mangling），子类无法直接覆盖，不是“绝对私有” -
ALL_CAPS：必须是真正不变的常量（如MAX_RETRY = 3），若赋值可变，就违背语义
最常被忽略的是模块名本身：utils.py 比 Utils.py 更符合 PEP 8，但很多初学者因 Windows 文件系统不区分大小写而误以为后者可行——一旦部署到 Linux，import Utils 就会报 ModuleNotFoundError。
