PEP 8 程序代码的编写风格指南

PEP 8 程序代码的编写风格指南

参考

PEP 8 -- Style Guide for Python Code

介绍

PEP ( Python Enhancement Proposals ) - Python 语言精进建议书

本份文件提供Python代码编写的守则, 有关为Python 语言以C语编写的部份请参考PEP 7.

如果某些项目具有特定的编写风格, 以该项目为主.

这个愚笨的代码编写一致性要求是来自于淘气鬼的一点小心思.

编者意见:
这守则太过繁杂, 想遵守的人看了都会疯了. 重点如果简单, 很多人自然会遵循去作. 要不是受到Python相关人员的提示要求, 我肯定不会去管PEP 8的要求, 顶多就是三件事: 每行不超过80个字, 排版对齐, 加上一些说明.
本文非直接翻译的结果, 如果有错误, 敬请提示.

代码被读的机会比编写的机会多, 这里的守则, 目的在于改善代码的可读性及各类不同应用的一致性.

不要只为了符合本守则, 而破坏了有关旧版的兼容性.

可以忽视本守则的原因:

  1. 当应用本守则时, 会造成可读性降低.
  2. 为了与周遭的代码一致, 可能是因为旧代码的存在.
  3. 在本守则建立以前的旧代码.
  4. 为了兼容与不支持本守则的旧版Python.

代码的布局

缩格

每一层级的缩格使用4个空格符, 不要使用Tab, 除非要兼容原已使用Tab缩格的代码.

使用大中小括号来分行时应该要作到垂直对齐, 其中段落中除第一行外, 其他各行都应该要缩格. 左括号是第一行的最后一个非空白字符, 并且没有任何的参数; 如果第一行的内容太短, 比如 if ( 就没有必要这么作. 右括号可以放在最后一行的第一个字.

如果分行的缩格无法与下一语句的缩格区分, 必须在分行前再加一级缩格.

每一行的最大长度

限制每一行的最大长度为79个字母. 文件说明或批注最大长度为72个字母. 尽可能使用括号来分行, 而不要使用倒斜线, 除非前者无法使用.

二元运算符 (+, - ,* ,/ , ... )

运算符前分行会更有可读性

空行的使用

  • 顶层函数及类的定义应该前后加两个空行.
  • 类中的方法则前后加一个空行.
  • 相关功能的语句可以保守地使用空行与别的语句区隔.
  • 单行语句的空行可以省略.
  • 函数中逻辑的部份可以保守地使用空行.

源代码的编码方式

  • 永远都使用 UTF-8 (在 Python 2 中使用的是 ASCII)
  • 使用 UTF-8 或 ASCII 不应该有编码的宣称.
  • 标准库中, 非省缺的编码只能用在测试时或文件说明及批注中, 否则使用 \x, \u, \U 或 \N 脱离字符来包含非ASCII的资料.
  • 标准库中, 所有的标示符必须使用ASCII, 也应该是英文字母. 字符串及批注也必须是ASCII. 作者名是一个例外, 但必须转译为拉丁字母表 ( latin-1 )

Import

  • import 语句应该放在模块批注及文件说明之后, 模块全局变量及常数之前.
  • import 应该分为三群, 标准库, 第三方库, 自己的库; 用空行来分隔
  • 建议使用絶对路径 import; 标准库应该使用絶对路径 import. 不要使用隐式相对路径的 import, Python 3 已经移除这种方式.
  • 不要使用 import *, 会造成命名的混淆或重复.
  • 不同模块不要写在同一个 import 语句中, 同一个模块可以写在一个import 语句中.

模块级的双底线变量名

  • 除了 from __future__ import 以外, 所有双线的变量名宣称应该放在文件说明之后, 其他 import 之前. Python 指定 from __future__ import 必须放在文件说明之后, 以及其他代码之前.

字符串引号

  • 字符串的引号使用单引号或双引号都是可以的.
  • 文件说明则要使用三个双引号.

表达式与语句中的空格

  • 避免额外多余的空格
  • 括号前不要有空格.
  • 逗号前不要有空格.
  • 冒号前后空格数量要一样.
  • 函数名, 类名及变量名后要紧接括号.
  • 不要为了对齐某个字而增加空格, 比如等号.

其他建议

  • 每一行的后面不要有空格.
  • 运算符前后都加上一个空格.
  • 不同运算顺序的运算符, 可以考虑在运算顺序较后的运算符前后各加一个空格.
  • 非 -> 的关键词及缺省值所使用的等号前后不要有空格. -> 时则要加空格.
  • -> 前后各加一个空格.
  • 不要使用超过一个的空格.
  • 不建议使用组合单行的语句

逗号在后

  • 只有一个元素的Tuple使用, 必须在括号内使用.

批注

  • 代码更新时, 也请更新批注.
  • 批注要是一个完整的句子; 第一个字除非是变量名, 否则应该要大写; 每个句子结束要有句点; 两个句子之间应该要有两个空格.
  • 英文书写请依循 "Strunk and White" ( 英文写作指南 ).
  • 除非很确定代码不会被其他语言国家的人来读, 否则请以英文来书写.
  • 区块批注中的段落使用一个 # 的空行来分隔.
  • 行批注少用, 使用时, 至少空两个空格, # 后加一个空格, 语意明显的就不用说明

文件说明字符串

  • 守则请看PEP 257.
  • 对所有的公开模块, 函数, 类以及方法, 要写文件说明字符串.
  • 非公开的部份, 应该要有批注说明其用意, 批注放在 def 下一行.
  • """ 要单独放在文件说明字符串的最后一行, 除非只有一行.

名字定义方式

  • 名字定义的方式所要反应的是用法, 而不创建.
  • 前置字在模块用来群组化是没有意义的, 因为模块带头已经说明了一切.
  • 前有一底线的, 为弱内部使用, 在 import * 中, 不会被引入.
  • 后有一底线的, 用来避免与Python的闗键字混淆.
  • 前有双底线的, 会造成与类名连接, 引起混淆.
  • 前后有双底线的只在用户所有的名空间内.

命名守则

  • 不要用小写的 L, 大写的 O, 大写的 I, 来作为单字母的变量名.
  • 使用 ASCII 变量名.
  • 模块/库 - 短的全小写字母 (+中间底线, 不建议使用), C/C++模块前面要加一个底线.
  • 类 - 大写字母开头的字组
  • 内建 - 单一或两个字的组合, 大写字母开头的字组只适用在exception名, 以及常数.
  • 变量名定义在 PEP 484, 为优先使用大写字母开头的字组, 后面加底线再加小写的字, 以代表相应的变量.
  • 异常名字 - 同类的方式, 后面应加上底线及Error.
  • 全局变量 - 在单一模块内使用, 如函数名一样, 旧守则是在前面加上一个底线.
  • 函数及变量名 - 全小写字母, 或可加上居中底线, 混合方式只限定已有的样式, 以达到兼容要求.
  • 函数与方法的参数 - 类的方法使用 cls 作为第一个参数, 实例方法使用 self 作为第一个参数. 如果函数的参数与关键词冲突, 最好是加一个后底线, 或使用同意字, 而不是改名字.
  • 方法与实例 - 小写字母, 或可加上居中底线, 如果是私有的方法或实例, 加一个前底线.
  • 避免与子类冲突, 加前双底线, 将无法被外部直接取用, 但可间接取用(模块名._模块名+变量名)
  • 常数 - 全大写+中底线
  • 公开的部份, 修改可能要考虑兼容的问题; 公开的部份则不需要. 没有文件说明的接口都被视为非公开的.
  • 公开的属性没有前底线, 与关键词冲突则加后底线.

编程建议

  • 代码的编写不会破坏其他的代码. 比如字符串的相加, 不要用 + 号, 最好是使用 ''.join()
  • 单态类的比较, 使用 is 或 is not, 而不要用 == 或 !=; 逻辑类的if result, 最好是 if result is not None. 使用 is not, 而不是 not is.
  • 顺序的比较最好是使用 (__eq__, __ne__, __lt__, __le__, __gt__, __ge__), 可以用在不同的种类比较上. 可以参考 functools.total_ordering(), PEP 207.
  • 使用 def 好过使用 lambda
  • 从 Exception 找异常, 而不是从 BaseException 去找. PEP 3151
  • Exception 发生时, 应该把相关的细节都回传到新的 Exception.
  • 指明发生的异常, 而不是只有 except:.
  • try中的语句越少越好.
  • 当来源只适用某些语句时, 使用 with 方法/函数.
  • 所有的情况都应明白指出返回的结果.
  • 使用字符串方法, 而不是使用字符串模块.
  • 使用 ''.startswith() 与 ''.endswith() 代替检查字符串的前后文.
  • 使用 isinstance() 来检查类型, 而不是type().
  • 空的string, list 与 tuple代表的是False.
  • 字符串中后面的空格可能会被删除.
  • 不要用 == 或 is 来比较 逻辑值.
  • 不要在 try ... finally 中使用 return/break/continue.
本作品采用《CC 协议》,转载必须注明作者和本文链接

Jason Yang

讨论数量: 2

要不发布个文档,然后你自己翻译,这样曝光度还高些。真的 :+1:

6个月前 评论
Jason990420

@娃哈哈店长 主要是内容简化, 一份文件动不动几百页的, 那大伙得看多久. 所以整份文件的翻译真没想作.

6个月前 评论

请勿发布不友善或者负能量的内容。与人为善,比聪明更重要!