PEP 8风格指南:编写规范、可读、可协作的Python代码
PEP 8风格指南:编写规范、可读、可协作的Python代码
PEP 8是Python社区最具影响力的代码风格规范,它定义了缩进、空行、命名、表达式写法等一整套约定。本文以番外篇/PEP8风格指南.md为核心骨架,结合本仓库番外篇/code与Day31-35/code中的真实源码,逐条讲解PEP 8的关键规则,并给出Pylint等落地工具的使用方式。读完本文,你将能够写出风格统一、易于阅读、经得起多人协作与代码评审检验的Python代码。
PEP 8是什么:Python社区的代码风格共识
PEP是Python Enhancement Proposal(Python增强提案)的缩写,每一份PEP都是一份为Python社区提供的、指导Python往更好方向发展的技术文档。其中第8号增强提案(PEP 8)正是针对Python语言本身编订的代码风格指南。
虽然Python允许我们在保证语法正确的前提下随意书写代码,但在实际开发中,采用一致的风格写出可读性强的代码,是每个专业程序员应当做到的事情,也是绝大多数公司编程规范中明确提出的要求。这一点在多人协作开发一个项目(团队开发)的场景下尤为重要:当多个开发者同时维护同一份代码库时,统一而清晰的风格能显著降低彼此的阅读成本与合并冲突。
PEP 8的核心精神与Python之禅(可通过import this查看,参见仓库中的番外篇/Python之禅的最佳翻译.md)一脉相承,其中最重要的两句是:
- "Readability counts."——可读性很重要;
- "There should be one-- and preferably only one --obvious way to do it."——做一件事应该有而且最好只有一种确切的做法。
后者传达的思想在PEP 8中无处不在:规则不是限制,而是帮助所有Python开发者用同一种"显而易见"的方式书写代码。
空格的使用:Python代码的骨架
Python与C/C++、Java最大的差异在于:它没有用花括号构造代码块的语法,分支、循环、函数体都依靠缩进来界定代码的归属层级。因此,缩进写得好不好,直接决定了代码是否可读、是否会出错。
用空格表示缩进,不要用制表符(Tab)
绝大多数习惯其他编程语言的程序员都会用Tab来表示缩进,但在Python中,这可能是"一场灾难":不同编辑器对Tab的渲染宽度可能是2、4、8个字符甚至更离谱的值,同一个文件在不同编辑器中打开会呈现完全不同的缩进层级,轻则影响阅读,重则引发IndentationError或逻辑错位。
每一层缩进用4个空格
和语法相关的每一层缩进都用4个空格来表示。这是PEP 8的硬性约定,也是Python社区最通行的默认值(大多数编辑器在Tab键上设置的默认行为就是插入4个空格)。
行长度与续行缩进
每行的字符数不要超过79个字符。如果表达式太长而占据多行,除首行之外的其余各行,都应该在正常的缩进宽度上再加4个空格。例如下面这种过长表达式的换行方式:
income = (gross_wages
+ taxable_interest
+ (dividends - qualified_dividends)
- ira_deduction
- student_loan_interest)
首行保持原缩进,后续每行在正常缩进宽度上额外增加4个空格,让读者一眼就能看出它们是前一行表达式的延续。
运算符两侧的空格
二元运算符的左右两侧应该各保留一个空格,而且只要一个空格就好。多余的空格(例如a + b)并不会带来任何收益,反而破坏了整齐的视觉节奏:
# 规范
total = price * quantity + shipping
# 不规范
total = price * quantity + shipping
仓库中的排序示例Day31-35/code/example02.py就严格遵循了这一约定,例如:
def select_sort(origin_items, comp=lambda x, y: x < y):
"""简单选择排序"""
items = origin_items[:]
for i in range(len(items) - 1):
min_index = i
运算符两侧各一个空格、逗号后跟一个空格、函数参数与括号之间不留空格,这些都是PEP 8在空格维度上的具体要求。
空行:代码的段落分隔
空行本身也是排版规则的一部分,它承担着"分段"的作用:
- 函数和类的定义,代码前后都要用两个空行进行分隔;
- 在同一个类中,各个方法之间应该用一个空行进行分隔。
在Day31-35/code/example02.py中可以清晰地看到这一规范:模块级文档字符串与第一个class之间空两行,class Person与下一个def select_sort之间空两行,各个def之间也空两行;而类内部的方法(如__init__、__str__、__repr__)之间只空一行:
class Person(object):
"""人"""
def __init__(self, name, age):
self.name = name
self.age = age
def __str__(self):
return f'{self.name}: {self.age}'
def __repr__(self):
return self.__str__()
def select_sort(origin_items, comp=lambda x, y: x < y):
"""简单选择排序"""
items = origin_items[:]
...
同样的风格也体现在Day31-35/code/example01.py中:模块级文档字符串之后空两行再写from导入语句,各函数之间空两行,main()函数末尾再通过if __name__ == '__main__':调用程序入口(这也是番外篇/Python编程惯例.md中强调的"让代码既可以被导入又可以被执行"的惯例)。
标识符命名:让名字自己说话
PEP 8倡导用不同的命名风格来命名Python中不同类型的标识符,使读者在阅读代码时,仅凭名字就能判断该标识符扮演的角色。(值得一提的是,PEP 8也承认Python自己的内置模块以及某些第三方模块在这方面做得并不是很好,但这不妨碍我们对自己代码的要求。)
| 标识符类型 | 命名风格 | 示例 |
|---|---|---|
| 变量、函数、属性 | 小写字母拼写,多单词用下划线连接 | total_price、selected_balls |
| 类中受保护的实例属性 | 以一个下划线开头 | _internal_value |
| 类中私有的实例属性 | 以两个下划线开头 | __password |
| 类、异常的命名 | 每个单词首字母大写 | Person、PrimeIter |
| 模块级别的常量 | 全大写,多单词用下划线连接 | MAX_CONNECTIONS |
| 实例方法的第一个参数 | self,表示对象自身 |
def __init__(self, name) |
| 类方法的第一个参数 | cls,表示类自身 |
def create(cls, config) |
仓库中的番外篇/code/test03.py(双色球随机选号示例)很好地体现了变量命名规范:
from random import randint, sample
# 初始化备选红色球
red_balls = [x for x in range(1, 34)]
# 选出六个红色球
selected_balls = sample(red_balls, 6)
# 对红色球进行排序
selected_balls.sort()
# 添加一个蓝色球
selected_balls.append(randint(1, 16))
red_balls、selected_balls都是多个单词用下划线连接的小写命名;而Day31-35/code/example01.py中的seq_search、bin_search、main则是函数命名,y_data1、y_data2等是变量命名,与def、class的语法结合后一目了然。
self与cls这两个约定看似微小,却至关重要:它们让实例方法、类方法、静态方法在调用约定上有了明确的身份标识,是面向对象代码可读性的基础。
表达式和语句:Pythonic的表达方式
PEP 8不仅在排版上给出规范,也在表达方式上给出指引。这一部分的核心理念依然是Python之禅——"做一件事应该有而且最好只有一种确切的做法"。
采用内联形式的否定词
不要把否定词放在整个表达式的前面。例如if a is not b就比if not a is b更容易让人理解:
# 推荐:否定词紧贴被否定的对象
if a is not b:
...
# 不推荐:需要额外思考才知道表达的含义
if not a is b:
...
不要用检查长度的方式判断空值
判断字符串、列表、字典等是否为None或没有元素,应该用if not x这样的写法,而不是if len(x) == 0或if x == []。if not x同时涵盖了"为空"与"为None"两类情况,更简洁也更符合Python的真值约定。这一点在番外篇/Python编程惯例.md中有直接的正反对照:
# 好的写法
if name and fruits and owners:
print('I love fruits!')
# 不好的写法
if name != '' and len(fruits) > 0 and owners != {}:
print('I love fruits!')
不要将单行语句与关键字写在一起
即使if分支、for循环、except异常捕获等结构中只有一行代码,也不要将代码和if、for、except写在同一行。分开写才清晰:
# 推荐
if user:
login(user)
# 不推荐
if user: login(user)
import语句的放置与排序
import语句总是放在文件开头的地方;- 引入模块时,
from math import sqrt优于import math——前者在后续代码中可以直接使用sqrt,避免反复写出math.sqrt; - 如果有多个
import语句,应该分为三部分,从上到下分别是Python标准模块、第三方模块和自定义模块,每个部分内部按模块名称的字母表顺序排列。
仓库代码正是这一规则的典型示范。Day31-35/code/example01.py在模块级文档字符串之后,先导入标准库模块,再导入第三方模块:
from math import log2, factorial
from matplotlib import pyplot
import numpy
而番外篇/code/test03.py则只使用了标准库:
from random import randint, sample
当项目逐渐变大、依赖逐渐增多时,"标准模块在前、第三方模块居中、自定义模块殿后,各组内按字母序排列"的约定会让依赖关系变得一目了然,也便于代码评审者快速发现冗余或缺失的导入。
让风格落地:Pylint等检查工具的使用
规范写得再好,如果完全依赖人眼审查,效率依然有限。借助静态检查工具可以让PEP 8的执行自动化。仓库公开课文档公开课/年薪50W+的Python程序员如何写代码/年薪50W+的Python程序员如何写代码.md中详细介绍了Pylint——一款分析Python代码错误、查找不符合代码风格标准(默认使用的风格标准正是PEP 8)及潜在问题的工具。
安装与基本用法:
pip install pylint
pylint [options] module_or_package
Pylint的输出格式为模块名:行号:列号: 消息类型 消息,消息类型分为五类:
C- 惯例(Convention):违反了Python编程惯例(PEP 8)的代码;R- 重构(Refactor):写得比较糟糕、需要重构的代码;W- 警告(Warning):代码中存在但不影响运行的问题;E- 错误(Error):代码中存在且影响运行的问题;F- 致命错误(Fatal):导致Pylint无法继续运行的错误。
Pylint的常用参数包括:
--disable=<msg ids>或-d <msg ids>:禁用指定类型的消息;--errors-only或-E:只显示错误;--rcfile=<file>:指定配置文件(团队可用统一配置文件实现风格基线);--list-msgs:列出Pylint的消息清单;--generate-rcfile:生成配置文件的样例;--reports=<y_or_n>或-r <y_or_n>:是否生成检查报告。
将Pylint接入日常开发流程(例如提交前检查、CI流水线),可以把"是否符合PEP 8"从主观判断变成可机器验证的客观标准。除了Pylint,pycodestyle、black等工具也是社区常用的风格检查与自动格式化工具,读者可根据团队约定选择。
从规范到实践:用真实代码检验
PEP 8的价值最终体现在真实代码上。以番外篇/code/test.py中的归并排序merge函数为例:
def merge(items1, items2):
items3 = []
index1, index2 = 0, 0
while index1 < len(items) and index2 < len(items2):
if items[index1] < items2[index2]:
items3.append(items1[index1])
index1 += 1
else:
items3.append(items2[index2])
index2 += 1
这段代码在缩进(4空格)、运算符两侧空格、函数内部结构上都符合PEP 8,但items1与items混用暴露出命名一致性问题——len(items)显然应为len(items1)。这恰好说明:规范的缩进和排版只是"形",标识符命名的一致性才是"神",两者结合才能真正减少bug。
再看Day31-35/code/example02.py中的bubble_sort,它展示了PEP 8命名规范与函数签名的组合用法:
def bubble_sort(origin_items, *, comp=lambda x, y: x > y):
"""冒泡排序"""
items = origin_items[:]
...
origin_items(原始列表,不修改入参)与items(排序过程中的副本)都是清晰的小写下划线命名;comp参数使用lambda作为默认值,配合*强制关键字参数。这些细节共同构成了专业、可维护的代码风格。
结语
PEP 8不是教条,而是一套被Python社区长期验证过的工程实践。它让代码的"外表"统一,从而让团队可以把注意力集中在"逻辑"上。建议读者在完成Python-100-Days的学习过程中,随手对照本文的规则审视自己写过的代码,并配合Pylint等工具形成检查习惯。
仓库中还收录了与本文直接相关的两篇姊妹篇,可作为延伸阅读:
- 番外篇/Python编程惯例.md:汇总了EAFP优于LBYL、用
enumerate迭代、用join构建字符串等Pythonic惯例,与PEP 8互为补充; - 番外篇/Python之禅的最佳翻译.md:PEP 8精神内核的完整出处,值得逐条品味。