在Python项目里,代码不只是给解释器执行的指令,也是给同事和未来的自己阅读的文档。PEP 8(Python Enhancement Proposal 8)就是Python社区公认的代码风格指南,全称 Style Guide for Python Code,由Guido van Rossum与Barry Warsaw共同编写,2001年7月5日首次发布,之后经过多次修订,覆盖命名、布局、注释和编程建议等部分。原文提到,遵循统一编码规范的团队代码审查效率提升约40%,Bug修复时间缩短约25%,新成员上手时间平均缩短约30%。这些数据的具体口径不必过度解读,但方向很明确:风格统一能直接降低协作成本。
一、先理解PEP 8的定位
PEP(Python Enhancement Proposal)是Python社区提出新特性、记录设计决策、建立编码规范的标准文档体系,PEP 8是其中最基础的一份。它解决的是一致性问题,而不是审美争论。PEP 8开篇引用了“愚蠢的一致性是狭隘心灵的怪物”这句话,含义是:不要为了机械符合规范而大改已有代码。进入一个已有项目时,应优先沿用项目现有风格,一致性比“纯粹正确”更重要。
- def calculate(x,y,z):
- if x>0:
- return x+y+z
- else:
- return 0
复制代码
上面这段能运行,但拥挤难读;改写成下面这样,空白和文档字符串同时到位:
- def calculate(x, y, z):
- """计算三个数的和,如果x为非正数则返回0"""
- if x > 0:
- return x + y + z
- else:
- return 0
复制代码
二、缩进与代码布局
缩进是Python区分代码块的语法基础。PEP 8要求每个缩进级别使用4个空格,空格与制表符不能混用,Python 3明确禁止混用,混用会抛出TabError。
- def process_data(data):
- if data:
- for item in data:
- if item > 0:
- print(item)
复制代码
一行过长需要换行时,续行有两种常见对齐方式:与开括号对齐,或者使用悬挂缩进(比当前层级多缩进一级)。if条件续行时,要在续行上增加额外缩进,以区分续行和代码块本体,通常还会在条件两侧加括号:
- if (this_is_one_thing
- and that_is_another_thing):
- do_something()
复制代码
行宽方面,PEP 8规定每行不超过79个字符,文档字符串或注释不超过72个字符。这条规则争议最大,但初衷是让标准终端能并排打开两个文件、方便代码审查工具对比。超长代码应拆行,长字符串可用相邻字符串隐式拼接:
- result = some_function(
- param1, param2, param3,
- param4, param5, param6,
- param7, param8, param9,
- )
- long_message = (
- "This is a very long message that needs to be "
- "split across multiple lines for better readability. "
- "Python will automatically concatenate adjacent strings."
- )
复制代码
空行规则:顶层函数和类定义之间用两个空行分隔,类内部方法之间用一个空行分隔,逻辑相关的代码组之间可以额外加空行。
import导入也有固定顺序:每个导入独占一行,按“标准库 > 第三方库 > 本地模块”分组,组间用空行隔开,避免 from module import * 这种污染命名空间的写法,绝对导入优先于相对导入。
- import os
- import sys
- from datetime import datetime, timedelta
- import numpy as np
- import pandas as pd
- from flask import Flask, request
- from mypackage import utils
- from mypackage.models import User
复制代码
三、命名规范
命名是Python可读性的核心。规则可以归纳为:模块名用小写加下划线;类名用驼峰命名法(CapWords);异常类用驼峰加Error后缀;函数、方法、变量用全小写加下划线;常量用全大写加下划线;私有属性或方法加单下划线前缀;触发名称改写用双下划线前缀;魔法方法用双下划线前后缀。
- class DataValidationError(Exception):
- pass
- def get_user_by_id(user_id):
- pass
- MAX_CONNECTIONS = 100
- DEFAULT_TIMEOUT_SECONDS = 30
- class DatabaseConnection:
- def __init__(self):
- self._connection = None
- self._is_connected = False
- def _connect_internal(self):
- pass
复制代码
要避免的命名包括:单字符变量(i、j、k作计数器或迭代变量除外,l、O、I容易与数字混淆)、与内置函数或类型冲突的名称(list、str、max)、以及把类型信息写进变量名的匈牙利命名法(如str_name、int_age)。后者的替代做法是用有意义的名称,类型信息交给类型提示。
四、表达式和语句中的空格
空格规则的目标是分隔语法元素,同时不让人误读。二元运算符和赋值运算符两侧各加一个空格;函数参数默认值的等号两侧不加空格;切片中冒号两侧不加空格,只有冒号两侧都有表达式时才加等量空格;逗号、分号、冒号后加空格,前面不加;括号内不加空格;行尾不留空格,空行不包含任何空白字符。
- result = a + b
- total = price * quantity
- is_valid = (age >= 18) and (age <= 65)
- def greet(name, greeting="Hello"):
- return f"{greeting}, {name}"
- greet(name="Bob", greeting="Hi")
- text[1:4]
- numbers[::2]
- config = {'host': 'localhost', 'port': 8080}
复制代码
需要在一段长表达式里换行时,推荐把运算符放在新行开头,视觉上更整齐:
- income = (gross_wages
- + taxable_interest
- + (dividends - qualified_dividends)
- - ira_deduction
- - student_loan_interest)
复制代码
五、注释与文档字符串
注释的原则是解释“为什么”,而不是“是什么”。如果代码已经足够清楚,就不必再写注释;与代码不一致的注释比没有注释更糟。块注释缩进与代码一致,每行以#加一个空格开头;行内注释尽量少用,与代码至少间隔两个空格。
文档字符串是模块、函数、类或方法的第一条语句,用三重引号包裹,具体格式由PEP 257规定,通常包含功能描述、Args、Returns、Raises、Examples等段落。
- def calculate_bmi(weight_kg: float, height_m: float) -> float:
- """
- 计算身体质量指数(BMI)。
- BMI的计算公式为:体重(kg) / 身高(m)的平方。
- Args:
- weight_kg: 体重,单位为千克
- height_m: 身高,单位为米
- Returns:
- BMI值,保留一位小数
- Raises:
- ValueError: 如果体重或身高为非正数
- Examples:
- >>> calculate_bmi(70, 1.75)
- 22.9
- """
- if weight_kg <= 0 or height_m <= 0:
- raise ValueError("体重和身高必须为正数")
- bmi = weight_kg / (height_m ** 2)
- return round(bmi, 1)
复制代码
六、编程建议与常见错误
比较运算:判断None时使用is和is not,不写 not x is None,也不写 value == None;判断布尔值时直接使用变量本身,不写 == True;判断序列是否为空时用 if not items,而不是 len(items) == 0。
异常处理:捕获具体异常类型,避免裸 except 吞掉KeyboardInterrupt等系统异常;需要多分支时使用try-except-else-finally结构,else只在try块无异常时执行,finally无论是否发生异常都会执行。
- try:
- file = open('data.txt')
- except FileNotFoundError:
- print("文件不存在")
- else:
- content = file.read()
- file.close()
- finally:
- print("操作完成")
复制代码
返回语句:函数应保持一致的返回类型,避免一处返回对象、另一处返回False;能直接返回布尔表达式结果的,就不要写if-else两块返回True/False。
字符串操作:拼接字符串列表用 ' '.join(items),不要在循环里用 += 累加;检查前后缀用startswith/endswith,而不是切片比��;检查子串用 in,而不是 find(...) != -1。
常见错误集中在几处:用Tab缩进、行尾残留空格、顶层函数之间缺少两个空行、单行过长、import顺序混乱、以及用内置名当变量名。这些问题人工检查成本高,交给工具更可靠。
七、用自动化工具落地
原文列出了常用工具:flake8做代码风格检查,pylint做全面代码分析,black做自动格式化,autopep8做PEP 8自动格式化,isort做导入排序,mypy做类型检查,均可通过pip install安装,例如 pip install flake8 后执行 flake8 mycode.py。
flake8可以在setup.cfg或tox.ini中配置行宽、排除目录和忽略规则;black、isort、mypy可以统一写进pyproject.toml:
- # setup.cfg 或 tox.ini
- [flake8]
- max-line-length = 100
- exclude = .git,__pycache__,docs,venv,migrations
- ignore = E203, W503
- per-file-ignores =
- __init__.py: F401
复制代码- # pyproject.toml
- [tool.black]
- line-length = 100
- target-version = ['py38', 'py39', 'py310', 'py311']
- [tool.isort]
- profile = "black"
- line_length = 100
- [tool.mypy]
- python_version = "3.10"
- warn_return_any = true
- warn_unused_configs = true
- disallow_untyped_defs = true
复制代码
配置好之后把这些命令接入开发流程(提交前钩子或CI),比在代码审查里逐条指出空格问题要高效得多。需要注意的是,如果把行宽改成100,就要在团队内保持一致,不要让flake8、black和编辑器各说各话——这恰好回到了PEP 8的第一原则:一致性优先。
八、编辑器层面的配合
要让缩进规则真正落地,编辑器配置不能缺。VS Code可以设置 editor.tabSize 为4、editor.insertSpaces 为true、editor.detectIndentation 为false;PyCharm在 File > Settings > Editor > Code Style > Python 中关闭“Use tab character”,并把Tab size设为4。大多数编辑器还提供“保存时删除行尾空格”选项,能直接消灭最常见的低级问题。
把规范、工具和编辑器三者对齐之后,PEP 8就不再是一份需要背诵的文档,而是开发流程里自动生效的默认行为。 |