Python 编码风格指南
本文超出 PEP8 的范畴以涵盖我认为优秀的 Python 风格。本文虽然坚持己见，却不偏执。不仅仅涉及语法、模块布局等问题，同时深入范式、组织及架构的领域。希望本文能成为精简版 Python 代码《风格的要素》。
目次
- Python 风格要素
- 基本遵从 PEP 准则
- 灵活的单行长度
- 一致的命名
- 不要在这些地方吹毛求疵
- 写好文档字符串
- 范式和模式
- 代码风格小禅理
- 平分秋色
- 标准工具及项目架构
- 灵感来源
- 撰稿人
基本遵从 PEP 准则
…… 但是，命名和单行长度更灵活。
PEP8 涵盖了诸如空格、函数/类/方法之间的换行、import、对已弃用功能的警告之类的寻常东西，大都不错。
应用这些准则的最佳工具是 flake8，还可以用来发现一些愚蠢的语法错误。
PEP8 原本只是一组指导原则，不必严格甚至虔诚地信奉。一定记得阅读 PEP8 「愚蠢的一致性就是小人物的小妖精」一节。若要进一步了解，可以听一下 Raymond Hettinger 的精彩演讲，「超越 PEP8」。
唯一引起过多争议的准则事关单行长度和命名。要调整起来也不难。
灵活的单行长度
若是厌烦 flake8 死板的单行长度不得超过 79 个字符的限制，完全可以忽略或修改这一准则。这仍然不失为一条不错的经验法则，就像英语中句子不能超过 50 个单词，段落不能超过 10 个句子之类的规则一样。这是 flake8 配置文件 的链接，可以看到 max-line-length 配置选项。值得注意的是，可以给要忽略 flake8 检查的那一行加上 # noqa 注释，但是请勿滥用。
尽管如此，超过九成的代码行都不应该超过 79 个字符，原因很简单，「扁平胜于嵌套」。如果函数每一行都超出了 79 个字符，肯定有别的东西出错了，这时要看看代码而不是 flake8 配置。
一致的命名
关于命名，遵循几条简单的准则就可以避免众多足以影响整个小组的麻烦。
推荐的命名规则
下面这些准则大多改编自 Pacoo 小组。
- 类名：
驼峰式和首字母缩略词：HTTPWriter优于HttpWriter。 - 变量名：
lower_with_underscores。 - 方法名和函数名：
lower_with_underscores。 - 模块名：
lower_with_underscores.py。（但是不带下划线的名字更好！） - 常量名：
UPPER_WITH_UNDERSCORES。 - 预编译的正则表达式：
name_re。
通常都应该遵循这些准则，除非要参照其他工具的命名规范，比如数据库 schema 或者消息格式。
还可以用 驼峰式 给类似类却不是类的东西命名。使用 驼峰式 的主要好处在于让人们以「全局名词」来关注某个东西，而不是看作局部标记或动词。值得注意的是，Python 给 True，False 和 None 这些根本不是类的东西命名也是用 驼峰式。
不要用前缀后缀
…… 比如 _prefix 或 suffix_ 。函数和方法名可以用 _prefix 标记来暗示其是「私有的」，但是最好只在编写预期会广泛使用的 API 以及用 _prefix 标记来隐藏信息的时候谨慎使用。
PEP8 建议使用结尾的下划线来避免与内置关键字重名，比如：
| 12 | sum_ = sum(some_long_list)print(sum_) |
临时这样用也可以，不过最好还是选一个别的名字。
用 __mangled 这种双下划线前缀给类/实例/方法命名的情况非常少，这实际上涉及特殊的名字修饰，非常罕见。不要起 __dunder__ 这种格式的名字，除非要实现 Python 标准协议，比如 __len__；这是为 Python 内部协议保留的命名空间，不应该在其中增加自定义的东西。
不要用单字符名字
（不过）一些常见的单字符名字可以接受。
在 lambda 表达式中，单参数函数可以命名为 x 。比如：
| 1 | encode = lambda x: x.encode(\”utf-8\”, \”ignore\”) |
解包元组时可以用 _ 丢弃不需要的标记。比如：
| 1 | _, url, urlref = data |
意思就是说「忽略第一个元素」。
和 lambda 类似，在解析列表/字典/集合的时候，以及在生成器表达式或者一到两行的 for 循环中，可以使用单字符迭代标记。通常选择 x，比如：
| 1 | sum(x for x in items if x > 0) |
可以求 items 序列中所有正整数之和。
此外比较常见的是 i，代表 index，通常和内置的 枚举 一起使用。比如：
| 12 | for i, item in enumerate(items): print(\”%4s: %s\” % (i, item)) |
除却上述情形，要极少甚至避免使用单字符用作标记/参数/方法的名字。因为这样就无法用 grep 进行检索了。
使用 self 及类似的惯例
应该：
- 永远将方法的第一个变量命名为
self - 永远将
@classmethod的第一个参数命名为cls - 永远在变量参数列表中使用
*args和**kwargs
不要在这些地方吹毛求疵
不遵循如下准则没有什么好处，干脆照它说的做。
永远继承自 object 并使用新式类
| 1234567 | # badclass JSONWriter: pass # goodclass JSONWriter(object): pass |
对于 Python 2 来说遵循这条准则很重要。不过由于 Python 3 所有的类都隐式继承自 object，这条准则就没有必要了。
不要在类中重复使用实例标记
| 12345678910 |
| 12 | sum_ = sum(some_long_list)print(sum_) |
临时这样用也可以，不过最好还是选一个别的名字。
用 __mangled 这种双下划线前缀给类/实例/方法命名的情况非常少，这实际上涉及特殊的名字修饰，非常罕见。不要起 __dunder__ 这种格式的名字，除非要实现 Python 标准协议，比如 __len__；这是为 Python 内部协议保留的命名空间，不应该在其中增加自定义的东西。
不要用单字符名字
（不过）一些常见的单字符名字可以接受。
在 lambda 表达式中，单参数函数可以命名为 x 。比如：
| 1 | encode = lambda x: x.encode(\”utf-8\”, \”ignore\”) |
解包元组时可以用 _ 丢弃不需要的标记。比如：
| 1 | _, url, urlref = data |
意思就是说「忽略第一个元素」。
和 lambda 类似，在解析列表/字典/集合的时候，以及在生成器表达式或者一到两行的 for 循环中，可以使用单字符迭代标记。通常选择 x，比如：
| 1 | sum(x for x in items if x > 0) |
可以求 items 序列中所有正整数之和。
此外比较常见的是 i，代表 index，通常和内置的 枚举 一起使用。比如：
| 12 | for i, item in enumerate(items): print(\”%4s: %s\” % (i, item)) |
除却上述情形，要极少甚至避免使用单字符用作标记/参数/方法的名字。因为这样就无法用 grep 进行检索了。
使用 self 及类似的惯例
应该：
- 永远将方法的第一个变量命名为
self - 永远将
@classmethod的第一个参数命名为cls - 永远在变量参数列表中使用
*args和**kwargs
不要在这些地方吹毛求疵
不遵循如下准则没有什么好处，干脆照它说的做。
永远继承自 object 并使用新式类
| 1234567 | # badclass JSONWriter: pass # goodclass JSONWriter(object): pass |
对于 Python 2 来说遵循这条准则很重要。不过由于 Python 3 所有的类都隐式继承自 object，这条准则就没有必要了。