1. PEP 8到底是什么新手为什么绕不开它1.1 一个真实的代码事故现场先讲一件我早年翻车的事。刚接触Python那会儿我觉得代码能跑就万事大吉缩进乱七八糟变量名随手就写一个函数能挤下几十行逻辑。直到某天接了一个别人的项目需要修改一段两百多行的脚本——那段代码缩进用的Tab还混着几个空格所有变量都叫a、b、tmp函数名也是f1、f2。我当时人麻了光是搞明白哪个f对应哪段逻辑就花了大半天改完之后还不敢保证有没有改错。这不是笑话而是所有Python新手在成长路上几乎都会撞上的墙。你一个人写代码的时候什么样的风格都无所谓机器不挑食能解释执行就行。可一旦代码要给别人看或者一个月后的自己要回来看代码风格就是决定你工作效率的隐形天花板。而这个问题的标准答案就是Python社区的官方代码风格规范PEP 8。PEP 8的全称是Style Guide for Python Code也就是Python代码风格指南。它由Guido van RossumPython之父和Barry Warsaw等人编写经过社区多年迭代成为事实标准。它不解决代码怎么执行的问题解决的是代码怎么写才像Python的问题——包括缩进、命名、空行、注释、表达式布局等方方面面。1.2 PEP 8不是约束是团队协作的共同语言很多新手一听到规范标准这两个词本能地觉得头大是不是又要背什么考试大纲了是不是写代码还要被条条框框捆住手脚我当年也是这么想的后来才明白PEP 8与其说是对学生一样的管束不如说是整个Python社区约定俗成的普通话。想象一下你加入一个项目组仓库里有几万行代码。如果每个人的写法都不一样——有人缩进用两个空格有人用Tab有人变量叫userName有人叫user_name有人喜欢一个函数写两百行有人习惯拆成十个短函数——那么你每次看代码都相当于在做翻译脑子还要在两种风格之间切换阅读效率直接腰斩。反过来如果所有人都按同一套规则来代码就像从同一个人手里写出来的你只管关心逻辑本身就行。PEP 8就是这套规则的底本。它不告诉你这段逻辑该怎么实现它告诉你的是无论逻辑是什么表达它的方式应该统一。这也是为什么我在带新人的时候第一周就让ta把PEP 8通读一遍不要求背但要求写出来的代码一眼看上去像那么回事。1.3 该不该盲目追随PEP 8关于PEP 8我特别想先打个预防针它是一条指南不是法律。它自己也写了A style guide is about consistency也就是风格规范的关键在于一致性。保持一致性比遵循某一条具体规定往往更重要。比如PEP 8建议行宽79字符但如果你所在团队的项目统一使用88字符比如配合Black格式化工具那也不是什么大问题关键是全项目保持一致。换句话说PEP 8给你的是一个默认选项如果一个项目里已经存在一套既有的风格约定优先跟既有风格走如果是从零起步的新项目那么跟着PEP 8走基本不会出大错。这篇博文接下来讲的就是我自己在实际工作中真正用得上、也最常拿出来教新手的那些规则配上一些示例和容易踩的坑。2. 命名规则给你的代码起个好名字2.1 变量、函数与模块蛇形命名法PEP 8规定的第一种关键命名法是snake_case蛇形命名用在变量名、函数名和模块名上全部小写字母单词之间用下划线分隔。比如user_name、get_total_amount、calculate_average_score都是典型的蛇形命名。很多从其他语言转过来的朋友习惯写驼峰命名比如userName、getTotalAmount。这在Java、JavaScript里没问题但在Python里PEP 8的建议是统一走蛇形。原因不复杂一是Python官方库和绝大多数第三方库都遵循这个约定你写requests.get(...)、os.path.join(...)函数名全部是蛇形二是全小写加下划线的风格阅读起来边界清晰尤其是对于英文水平一般的开发者getuserinfo和get_user_info哪个更好读不用多说。我自己还有一个体会写好变量名能大幅减少注释的需求。你写temp 10086读的人就不知道这是啥写customer_phone_number 10086读到这行就基本明白意图了。命名这个事儿多花几秒钟后面能省下几分钟乃至几十分钟的排查时间。需要注意的是PEP 8同时建议避免使用容易混淆的字符。比如l小写L和O大写O、I大写i在部分字体里几乎长一个样作为单字母变量很容易误读。写words [apple, banana]然后循环里用for w in words没问题但如果你非要写for l in list回头调试的时候绝对会花眼。2.2 类名CapWords驼峰命名法类的命名走的是另一条路CapWords也叫PascalCase也就是每个单词首字母大写、其余小写、单词间不加分隔符。比如class UserProfile、class HttpRequestHandler、class DatabaseConnection。规则本身很直白但我更想强调的是类为什么不用蛇形命名。一个很朴素的解释是代码里函数和变量用蛇形、类用驼峰扫一眼就能快速区分这是一个对象模板还是这是一个方法调用。比如看到UserProfile.objects.create(...)你立刻知道UserProfile是个类而objects是它的一个属性。如果你全用蛇形user_profile.objects.create(...)就和函数调用在视觉上失去区分度了。还有一个小细节异常类的命名也遵循CapWords但因为异常在代码里通常带Error后缀读起来更清楚。比如ValueError、TypeError、CustomValidationError。尽量避免给异常起error1、exception_a这类名字否则很难在except语句里判断到底要捕获哪一类错误。2.3 常量全大写加下划线常量一般指程序运行期间不会改变的值在Python里推荐用全大写加下划线比如MAX_CONNECTIONS 100、DEFAULT_TIMEOUT_SECONDS 30。这里必须说清楚一件事Python语言层面并没有真正的常量概念。你照样可以对MAX_CONNECTIONS重新赋值解释器也不会报错。全大写命名纯粹是一个约定——相当于在跟所有读代码的人说这个变量是固定的基础配置请勿修改。这是团队的纪律不是语言的强制。我自己写代码时习惯把常量定义在模块顶部集中在一起方便管理。如果项目中存在多类型配置还可以把同类常量归类到配置类或配置文件中免得散落各处。全大写命名最大的价值不在于好看而在于它让不被修改的值和可变化的运行期变量在视觉上彻底区分开。2.4 私有属性单下划线与双下划线的选择Python里没有真正的私有成员但PEP 8以及Python的惯例给出了两套约定信号_name单下划线开头表示内部使用外部不要直接访问。这个纯粹是约定外部依然可以调只是你应该把它当作请勿打扰的标志。__name双下划线开头会触发Python的**名称改写name mangling**机制让类外部无法轻易通过obj.__name访问到。多数情况下在类内部方法里访问self.__name没问题但外部访问就会变成obj._ClassName__name这种丑陋形式变相实现了私有。很多新手会纠结什么时候用单下划线什么时候用双下划线我实际项目里的经验有一个非常实用的判断标准——如果你确定在写一个会被子类继承的类且不希望子类不小心覆盖掉某些内部方法/属性就用双下划线如果只是提醒调用方这个别碰单下划线就够了。另外强烈建议不要把__name__这种双下划线开头又结尾的魔法方法/属性用于自定义命名。Python自己保留了大量__双下划线前后各两个下划线__的名称比如__init__、__str__、__len__等。你可别给变量起名叫__data__、__func__虽然不一定报错但容易让读代码的人误以为这是Python内建的特殊方法。走PEP 8的默认路线不要发明这种命名。2.5 命名规则的例外与团队习惯讲几个我踩过的例外情况。第一回调函数或者只用一次的临时函数变量名可以短一些比如在sorted(keylambda x: x.age)里用x完全合理不需要写成person_object。第二循环变量也允许单字母前提是循环体内层数浅、逻辑一目了然。但如果循环嵌套两层以上我建议至少写有意义的单词比如for row in matrix。命名这件事我和同事讨论时常用的一个说法是起名字的时间成本是几秒钟但名字的阅读次数可能是几百次、上千次。花在命名上的每一秒后面都会连本带利赚回来。这是我在实际项目里感受最深的一句话。3. 缩进、空行与行宽代码的排版美学3.1 为什么必须是4个空格PEP 8第一条硬规则就是缩进统一用4个空格不要用Tab更不要Tab和空格混用。Python里缩进不只是美观问题它是语法的一部分。你用Tab缩进写的代码到了别的编辑器里可能显示成8格宽度但解释器按Tab制表符解析很可能和你肉眼看到的逻辑层级完全不符最终报IndentationError或者更可怕的不报错但语义和你的意图不一样。更多的情况是团队协作时的混乱。如果小A用Tab缩进小B用4空格缩进两人同时改一个文件Git的diff会显示每一行都变动过代码评审根本没法看。我见过有团队专门写了一条规则谁往仓库里提交包含Tab缩进的文件就罚谁请下午茶。这听起来像玩笑其实是长期被坑之后的无奈之举。再说说为什么是4个空格而不是2个或8个2个空格在快速开发的早期很流行层级深的时候缩进级别不够明显8个空格在嵌套三层以后基本上就一行代码写不下了。4个空格是社区多年博弈后形成的平衡点多一层缩进看得清又不会很快把行宽撑爆。信我别折腾直接照做。如果实在讨厌手敲空格现代编辑器基本都支持缩进用空格的配置按下Tab键自动插入4个空格。例如VS Code右下角能设置Spaces: 4PyCharm的默认配置就是4空格。配置好之后你的Tab键实际上就是插入4个空格的快捷键。3.2 每行79字符的来历与价值PEP 8规定每行代码最多79个字符每行注释或文档字符串最多72个字符。很多新手第一反应是现在都是2K、4K大宽屏了79字符这个规矩还适用吗这个限制不是针对屏幕宽度的它的核心价值在于可读性和通用性。79字符的长度能保证在任何终端、任何编辑器、任何并窗对比的场景下都不会自动换行。当你需要把两个文件并排放在一起对比时窄行代码的优势立刻体现出来。另外在GitHub上审阅代码时超过一定宽度的行会自动折行折行之后代码的缩进和结构全乱读起来极其痛苦。实操中如果你觉得一行超过79字符不好拆最常用的办法是用括号隐式续行。比如说你有一个很长的函数调用result some_service_call( user_iduser.id, payload{name: user.name, age: user.age}, retry_count3, )在括号内部直接换行Python解释器是认可的不需要加反斜杠。拆完之后每个参数单独一行读起来清清楚楚。如果遇到那种明确要用二元运算符的长表达式PEP 8建议在运算符前换行而不是在运算符后换行这样能保证每行开头的运算符提示这行是上一行的延续total (first_variable second_variable - third_variable)记住一个原则能用圆括号解决的问题就不要用反斜杠续行。反斜杠续行\容易出错而且在行尾如果多敲了一个空格立刻报SyntaxError排查起来相当烦人。3.3 空行就是呼吸节奏PEP 8给了空行很明确的要求模块顶部的顶级定义函数、类之间空两行类内部的方法之间空一行函数内部可以用空行分隔逻辑上相对独立的段落空行的作用就像文章里的段落分隔。如果一个函数从上到下连敲了30行没有任何空行你很难一眼看出第一部分是做输入校验第二部分是核心计算第三部分是组装返回结果。适当空行之后读者扫一眼就能抓到几个逻辑块定位问题的效率高出一大截。我自己写函数的习惯是函数体如果超过10行就刻意想想能不能按逻辑分成两块块之间加空行并且在心里默念这一段只说一件事。空行不是装饰是你留给未来读者的路标。3.4 导入语句的规范导入import部分是一个看着不起眼、其实经常被新手写乱的区块。PEP 8的要求相当明确每个import单独一行不要写import os, sys这种合并写法导入分组顺序是标准库 - 第三方库 - 本地应用/库组与组之间空一行组内按字母顺序排列一个典型示例import json import os import requests import yaml from myproject.utils import format_phone为什么强调分组因为导入顺序能直观看出代码的依赖层次。如果这个文件先导了本地模块再导标准库说明写的人对代码的边界没有清晰认知。分组之后每次出问题你能迅速判断是标准库环境、第三方依赖还是本地代码导致的。这里有一个我要额外提醒的坑不要在函数内部写import除非有特殊原因比如规避循环导入。虽然语法合法但会让依赖关系变得不透明而且每次函数调用都要重新执行导入逻辑拖慢性能。保持导入集中在文件顶部是更符合PEP 8精神的做法。4. 注释与文档字符串写给下一个维护者4.1 注释写为什么而不是是什么刚学编程的时候老师强调代码要写注释于是很多人恨不得每隔一行就写一遍这行是给x赋值这个循环是遍历列表。等代码写多了才发现这类注释毫无营养因为代码本身已经表达了这些信息。真正有价值的注释是解释为什么要这样写尤其是那些从表面看不出来的背景和缘由。我举一个我自己项目里的例子。某段代码里有这样一行# 这里不用 dict.get是因为缺省值 None 需要参与后续逻辑判断 status result_dict[status]如果只从代码看result_dict[status]在key不存在时会直接抛KeyError为什么不换成更安全的get原因就在于注释里说的缺省值None需要参与后续逻辑判断——如果用了getkey不存在就返回None但None在后续逻辑里被当作已处理的空状态这就和异常分支混在一起了。注释写清楚之后后人就不会好心地把它改成get避免引入一个隐蔽的bug。PEP 8对注释的格式要求还有一条注释应与代码行分开写在代码上方而不是排在代码行末尾行内注释尽量少用。行内注释容易受行宽限制变得很挤而且如果代码改动后忘了同步更新注释行尾注释很可能变成精确的错误信息。更推荐的方式是单独一行注释缩进与下方代码保持一致。4.2 文档字符串docstring注释comment和文档字符串docstring在Python里是两件事。docstring是写在模块、函数、类、方法第一行的三重引号字符串用于描述它的用途和用法。PEP 8引用了PEP 257的约定同时规范了写法用三个双引号包围即使文档只有一行也用。一个合格的函数docstring至少要回答三个问题它是做什么的、参数是什么、返回什么。来看一个例子def calculate_bmi(weight_kg, height_m): 计算BMI指数。 Args: weight_kg (float): 体重单位公斤。 height_m (float): 身高单位米。 Returns: float: BMI值公式为体重除以身高的平方。 return weight_kg / (height_m ** 2)新手最容易犯的错是docstring写得太泛比如这是一个计算函数写等于没写。或者相反写得太长把实现细节全塞进去一旦逻辑更新文档立刻失真。我在团队里常跟新人强调的一句口诀是docstring描述能做什么注释解释为什么要这样代码本身承担怎么做。还有一个细节模块顶部的docstring可以写模块用途、维护者信息、版本号等但它应该放在该文件的任何import之前。函数内部的注释则保持精简尤其不要用注释去复述代码逻辑。4.3 注释里的小禁忌我总结几个实际工作中特别常见的注释问题新人们可以对照自查用注释替代删除代码。不要注释掉一大段代码留在那里想着可能以后还用得上。版本控制工具Git已经帮你保存历史了需要的时候去翻提交记录就行。注释掉的代码只会干扰阅读还容易让人误以为是当前生效的逻辑。写废话注释。比如i 1 # 让i加1这类注释没有传递任何增量信息是纯粹的噪音。注释里的中英文混排乱用。这不是PEP 8强制内容但团队里最好定一个习惯要么全中文注释要么全英文注释。我个人的经验是国内团队尽量用中文注释前提是团队所有人都能看懂但如果要开源建议全部英文因为全球的维护者都可能读你的注释。统一口径比一半中文一半英文要好得多。注释没有跟着代码一起更新。代码逻辑改了注释还停留在旧版本这比没有注释更可怕。我见过太多因为过时注释而错误判断逻辑的案例。所以看到注释和代码不一致优先相信代码但也要在改代码时顺手改注释。5. 表达式与语句的常见坑从写法看思维5.1 不要把多条语句挤在一行PEP 8明确建议一条语句占一行不要用分号把多条语句拼在同一行里。例如# 不推荐 x 1; y 2; z x y # 推荐 x 1 y 2 z x y你可能觉得多写两行浪费时间但挤在一行里的代码在调试时完全是灾难。断点都不知道该打在哪个表达式上。尤其是当某一行报错时如果那一行塞了三五个语句你根本没法从错误输出里快速定位具体是哪个部分出了问题。写代码是写给人和解释器共同看的人读得顺畅bug就容易找。5.2 判断与比较的正确姿势PEP 8在比较和条件判断上的规范很多新手一开始完全没概念等到被坑过之后才服气。先说与None的比较用is而不是。# 正确 if item is None: ... # 错误 if item None: ...原因在于None是Python里的单例对象singletonis比较的是是不是同一个对象比较的是值是否相等。一个自定义类完全可以重写__eq__让任何对象和None比较都返回True但is None则不受影响。另外涉及到惰性加载的ORM对象等情况时 None可能会触发隐式查询带来性能问题。同理判断布尔值时不要和True/False做比较# 新手写法 if is_ready True: ... # 更符合PEP 8直觉的写法 if is_ready: ... # 需要明确判断False时 if not is_ready: ...这条的核心逻辑是用真值测试truthiness代替显式的布尔比较。Python里空列表、空字符串、0、None、空字典在布尔上下文里都是False所以if items:比if len(items) 0:更地道也比if items ! []:更简洁。不过要注意如果你真的有列表为空但对象有效这种边界情况那就得用显式判断不能只看真值这是另一个层次的取舍。5.3 异常处理的范围PEP 8对异常处理也有明确倾向核心是两条异常捕获要具体不要用裸except。# 不好的写法捕获所有异常 try: process_data() except: logger.error(失败了)裸except会连KeyboardInterrupt按CtrlC和SystemExit一起吞掉用户想中断程序都没办法。更稳妥的写法是try: process_data() except ValueError as e: logger.error(数据格式错误: %s, e) except OSError as e: logger.error(文件或IO异常: %s, e)如果你确实需要兜底至少写成except Exception因为Exception不捕获键盘中断和系统退出相对安全得多。还有一个很多人没注意到的点try块要窄。不要把几十行无关联的代码全部丢进try里只包住可能抛异常的那几行就好。否则排错时你根本不知道异常是哪个操作触发的日志里的堆栈也被一堆无关代码稀释了。5.4 字符串拼接与空值判断新手写Python经常踩的另一个坑是字符串拼接。想象你要构建一条用户信息# 低效写法 s User: name , age: age , city: city这种写法的问题在于每次都会创建新的字符串对象循环里大量拼接时会带来不必要的内存开销。更Pythonic的写法是用f-stringPython 3.6s fUser: {name}, age: {age}, city: {city}f-string不仅简洁而且可读性强。PEP 8没有强制规定字符串格式化方式但它强调的可读性和一致性在这里体现得很充分。顺便一提多行字符串拼接也尽量别用\换行用()或三引号结构前面讲续行时已经提到过。再补充一个我培训新人时说的隐藏坑判断list是否为空时if not list是推荐的但有些场景要小心。如果代码需要严格区分列表不存在和列表为空那if list is None和if not list是两个完全不同的问题不要混在一起写。风格规范是为可读性服务的但它不能替你做业务判断。6. 工具链帮你守住PEP 8检查和自动格式化6.1 flake8最常用的检查器规范看完之后问题来了我记不住怎么办我的习惯是把检查交给工具让工具在你面前实时纠错。命令行下有一个经典组合叫flake8它集合了pycodestylePEP 8检查和pyflakes语法错误检查、mccabe圈复杂度检查一条命令就能报告代码里的风格问题和潜在逻辑隐患。安装和运行非常简单pip install flake8 flake8 your_codes.py输出的每一行都会有文件路径、行号、列号、错误码和说明。常见错误码比如E501line too long行太长、W291trailing whitespace行尾有多余空白、E128continuation line under-indented续行缩进不对。看到这些报错不用慌对着信息改就行。我实际操作中还会配合--max-complexity参数flake8 your_codes.py --max-complexity10如果某个函数的圈复杂度超过10说明它嵌套太深、分支太多建议拆成小函数。这个是mccabe提供的信号可以帮你发现一些风格之外的设计问题。6.2 black无情的格式化器flake8负责告诉你哪里不规范black则更进一步——直接帮你的代码自动格式化。black自称是uncompromising code formatter不让步的代码格式化器它有一套自己内置的规则几乎不允许任何参数配置。你只要运行black .它就会把目录下的所有Python文件重写一遍缩进、空格、引号、换行全部统一成black的标准格式。我第一次用black的感觉是这也太霸道了但它最大的好处恰恰是霸道。格式化这件事一旦允许个人偏好存在就永远吵不完有人喜欢行尾不加逗号有人喜欢加有人喜欢单引号有人喜欢双引号。black直接把这个争论消灭了——大家都别争用它说了算的格式。我在团队里的推荐用法是black负责格式化flake8负责查漏。black格式化完的代码基本能满足PEP 8的绝大部分规则但像行宽超了79字符这类规则black有它自己的容忍度默认88字符所以还是需要flake8配合纠偏。两者合起来才能达到既统一又不跑偏的效果。6.3 isort与pre-commit导入顺序靠肉眼维护是守不住的。尤其当项目文件几百上千个时不同人对标准库、第三方库、本地库的边界判断不一样很容易出现导入顺序混乱。isort就是解决这个问题的pip install isort isort your_codes.py它会自动把导入语句分组、按字母排序、去掉重复导入。结合black的配置还能保持一致的行尾风格。更进一步我建议在项目仓库里配置pre-commit在每次git commit之前自动跑格式化与检查。只要把配置文件写好团队每个人提交时都会先被工具教训一遍合不规范的代码根本进不了仓库。这个机制能大幅减轻代码评审的负担也算是我踩过手动检查漏网之鱼的坑之后总结出的最佳实践。pre-commit的配置模板现在很成熟GitHub上直接搜pre-commit就能拿到官方示例把black、flake8、isort三个钩子加上就够用。6.4 编辑器配置建议日常写代码时与其事后跑命令行不如直接在编辑器层面把规范前置。我常用的两个编辑器配置策略可以分享VS Code用户扩展市场里装Python扩展打开settings.json设置{ editor.formatOnSave: true, editor.rulers: [79], python.formatting.provider: black, python.linting.flake8Enabled: true, python.linting.lintOnSave: true, files.trimTrailingWhitespace: true }editor.rulers会在第79列显示一条参考线写代码时行宽超没超一眼可见。trimTrailingWhitespace自动去掉行尾空格从源头防止W291错误。PyCharm用户在Settings里搜索Code StylePython页面可以设置缩进为4空格、行宽为79。同时File - Settings - Tools - Python Integrated Tools里把Default Test Runner等选项配置好也可以在File Watchers里配置black自动格式化。编辑器设置这件事一次配置长期受益。我自己新入职一家公司或者新换电脑时第一件事永远是配好这套环境否则写出来的代码自己看着都不像话。6.5 不要被工具绑架人工审查看什么工具不是万能的。flake8能检查命名格式但不能检查命名是否表达准确black能统一格式但不能判断一个函数的职责是否太多。所以我在评审团队成员代码时会额外盯三件事变量名是否准确表达了业务含义。比如data这种名字在业务代码里等于没说至少要写成user_profile_data。函数长度和嵌套深度是否还在人能读懂的范围。我通常建议单个函数不超过30行嵌套不超过3层。注释和docstring是否印证了为什么的问题。看到代码里有一段奇怪的写法如果没有注释解释评审时我一定会要求补上。工具守住了可执行规范的底线但可读性的上限还是靠人的设计能力。这两者叠加才是PEP 8存在的真正意义。7. 一些写在最后的话别让规范变成心理负担最后再分享一点我个人的体会。很多新手听说PEP 8之后容易陷入两个极端要么觉得反正工具能检查我写完再格式化就行完全不在写的时候思考和规范相关的问题要么被各种规则吓到觉得代码风格是一个高深莫测的领域战战兢兢生怕哪一步就违规了。我的经验是PEP 8的学习曲线其实非常平缓。你不需要一次性记住所有规则只要记住几个核心原则——缩进统一用4空格、命名按蛇形驼峰全大写的口诀分类处理、空行让逻辑分段、注释多写为什么、长行用括号拆分。当你按这些原则写上一段时间它们就会变成你的肌肉记忆。之后再用flake8和black辅助检查你会发现自己写出的代码越来越标准而这种标准感带来的好处是实实在在的查bug快了、跟同事协作顺了、代码评审的返工少了。如果你正处在刚写完一个能跑的脚本这个阶段我建议你今天就做两件事打开编辑器配置好editor.rulers和flake8然后找一段自己以前写的代码按PEP 8的风格重写一遍。这一步做完你感受到的差距会比读十篇指南都直观。等你真正养成了风格意识再回去看那些较真的老程序员为什么对一两个空格的差异斤斤计较你大概也能会心一笑了。
