编码规范

Introduction

自Guido原始的《Python Style Guide》一文，同时添加了一些来自Barry的风格指南
项目风格一致性非常重要

Code lay-out 代码布局

续行缩进

foo=long_function_name(var_one,var_two,
                                         var_three,var_four)
def long_function_name(
					var_one,var_two,var_three,
					var_four)
			print(var_one)

对于多行结构可以这样

my_list=[
	1,2,3,
	4,5,5,
	]

最大行

Python标准库比较保守，需要将行宽限制在79个字符（文档/注释限制在72）
避免折行

with open('/path/to/some/file/you/want/to/read') as file_1, \
     open('/path/to/some/file/being/written', 'w') as file_2:
     file_2.write(file_1.read())

Should a line break before or after a binary operator? 在二元运算符之前应该换行吗？

几十年来，推荐的风格是在二元运算符之后中断。但是这回影响可读性，原因有二：操作符一般分布在屏幕上不同的列中，而且每个运算符被移到了操作数的上一行。下面例子这个情况就需要额外注意，那些变量是相加的，那些变量是相减的：

income = (gross_wages +
		taxable_interest +
		(dividends - qualified_dividends) -
		ira_deduction -
		student_loan_interest)

为了解决这种可读性的问题，数学家和他们的出版商遵循了相反的约定。Donald Knuth在他的Computers and Typesetting系列中解释了传统规则：“尽管段落中的公式总是在二元运算符和关系之后中断，显示出来的公式总是要在二元运算符之前中断”。

income = (gross_wages
		+ taxable_interest
		+ (dividends - qualified_dividends)
		- ira_deduction)

Blank Lines 空行

顶层函数和类的定义，前后用两个空行隔开。 类里的方法定义用一个空行隔开。 相关的功能组可以用额外的空行（谨慎使用）隔开。一堆相关的单行代码之间的空白行可以省略（例如，一组虚拟实现 dummy implementations）。 在函数中使用空行来区分逻辑段（谨慎使用）。 Python接受control-L（即^L）换页符作为空格；许多工具把这些字符当作页面分隔符，所以你可以在文件中使用它们来分隔相关段落。请注意，一些编辑器和基于Web的代码阅读器可能无法识别control-L为换页，将在其位置显示另一个字形。

Imports 导入

导入通常在分开的行

推荐
import os
import sys
不推荐
import os ,sys
可以
from subprocess import Popen, PIPE

• 导入总是位于文件的顶部，在模块注释和文档字符串之后，在模块的全局变量与常量之前。 导入应该按照以下顺序分组：

1. 标准库导入
2. 相关第三方库导入
3. 本地应用/库特定导入 你应该在每一组导入之间加入空行。
   • 推荐使用绝对路径导入，如果导入系统没有正确的配置（比如包里的一个目录在sys.path里的路径后），使用绝对路径会更加可读并且性能更好（至少能提供更好的错误信息）:

import mypkg.sibling
from mypkg import sibling
from mypkg.sibling import example

然而，显示的指定相对导入路径是使用绝对路径的一个可接受的替代方案，特别是在处理使用绝对路径导入不必要冗长的复杂包布局时：

from . import sibling
from .sibling import example

Module level dunder names 模块级的“呆”名

像__all__ , author , version 等这样的模块级“呆名“（也就是名字里有两个前缀下划线和两个后缀下划线），应该放在文档字符串的后面，以及除from future 之外的import表达式前面。Python要求将来在模块中的导入，必须出现在除文档字符串之外的其他代码之前。

"""
This module does stuff.
"""
from __future__ import barry_as_FLUFL
__all__ = ['a', 'b', 'c']
__version__ = '0.1'
__author__ = 'Cardinal Biggles'
import os
import sys

Whitespace in Expressions and Statements 表达式和语句中的空格

Pet Peeves 不能忍受的事情
空格一般不出现在语句中
功能型注释应该使用冒号的一般性规则，并且在使用->的时候要在两边加空格。

推荐
def munge(input: AnyStr): ...
def munge() -> AnyStr: ...
不推荐
def munge(input:AnyStr): ...
def munge()->PosInt: ...

当给有类型备注的参数赋值的时候，在=两边添加空格（仅针对那种有类型备注和默认值的参数）

推荐
def munge(sep: AnyStr = None):...
不推荐
def munge(input: AnyStr=None): ...

Comments 注释

与代码相矛盾的注释比没有注释还糟，当代码更改时，优先更新对应的注释！ 注释应该是完整的句子。如果一个注释是一个短语或句子，它的第一个单词应该大写，除非它是以小写字母开头的标识符(永远不要改变标识符的大小写！)。 如果注释很短，结尾的句号可以省略。块注释一般由完整句子的一个或多个段落组成，并且每句话结束有个句号。 在句尾结束的时候应该使用两个空格。 当用英文书写时，遵循Strunk and White （译注：《Strunk and White, The Elements of Style》）的书写风格。 在非英语国家的Python程序员，请使用英文写注释，除非你120%的确信你的代码不会被使用其他语言的人阅读。

Block Comments 块注释

块注释通常适用于跟随它们的某些（或全部）代码，并缩进到与代码相同的级别。块注释的每一行开头使用一个#和一个空格（除非块注释内部缩进文本）。 块注释内部的段落通过只有一个#的空行分隔。

行内注释

有节制地使用行内注释
行内注释是与代码语句同行的注释。行内注释和代码至少要有两个空格。

Naming Conventions 命名规范

Overriding Principle 最重要的原则
那些暴露给用户的API接口的命名，应该遵循反映使用场景而不是实现的原则。
Descriptive: Naming Styles 描述：命名风格
有许多不同的命名风格。这里能够帮助大家识别正在使用什么样的命名风格，而不考虑他们为什么使用。 以下是常见的命名方式：
• b（单个小写字母）
• B（单个大写字母）
• lowercase 小写字母
• lower_case_with_underscores 使用下划线分隔的小写字母
• UPPERCASE 大写字母
• UPPER_CASE_WITH_UNDERSCORES 使用下划线分隔的大写字母
• CapitalizedWords（或者叫 CapWords，或者叫CamelCase 驼峰命名法 —— 这么命名是因为字母看上去有起伏的外观5）。有时候也被称为StudlyCaps。 注意：当在首字母大写的风格中用到缩写时，所有缩写的字母用大写，因此，HTTPServerError 比 HttpServerError 好。
• mixedCase（不同于首字母大写，第一个单词的首字母小写）
• Capitalized_Words_With_Underscores（巨丑无比！）
也有用唯一的短前缀把相关命名组织在一起的方法。这在Python中不常用，但还是提一下。比如，os.stat()函数中包含类似以st_mode，st_size，st_mtime这种传统命名方式命名的变量。（这么做是为了与 POSIX 系统的调用一致，以帮助程序员熟悉它。） X11库的所有公共函数都加了前缀X。在Python里面没必要这么做，因为属性和方法在调用的时候都会用类名做前缀，函数名用模块名做前缀。 另外，下面这种用前缀或结尾下划线的特殊格式是被认可的（通常和一些约定相结合）：
• single_leading_underscore：（单下划线开头）弱“内部使用”指示器。比如 from M import * 是不会导入以下划线开始的对象的。
• single_trailing_underscore：（单下划线结尾）这是避免和Python内部关键词冲突的一种约定，比如：Tkinter.Toplevel(master, class_=’ClassName’)
• __double_leading_underscore：（双下划线开头）当这样命名一个类的属性时，调用它的时候名字会做矫正（在类FooBar中，__boo变成了_FooBar__boo；见下文）。
• double_leading_and_trailing_underscore：（双下划线开头，双下划线结尾）“magic”对象或者存在于用户控制的命名空间内的属性，例如：init,import__或者__file。除了作为文档之外，永远不要命这样的名。

Prescriptive: Naming Conventions 约定俗成：命名约定

Names to Avoid 应避免的名字

永远不要使用字母‘l’（小写的L），‘O’（大写的O），或者‘I’（大写的I）作为单字符变量名。 在有些字体里，这些字符无法和数字0和1区分，如果想用‘l’，用‘L’代替。

Package and Module Names 包名和模块名

模块应该用简短全小写的名字，如果为了提升可读性，下划线也是可以用的。Python包名也应该使用简短全小写的名字，但不建议用下划线。 当使用C或者C++编写了一个依赖于提供高级（更面向对象）接口的Python模块的扩展模块，这个C/C++模块需要一个下划线前缀（例如：_socket）

Class Names 类名

类名一般使用首字母大写的约定。 在接口被文档化并且主要被用于调用的情况下，可以使用函数的命名风格代替。
注意，对于内置的变量命名有一个单独的约定：大部分内置变量是单个单词（或者两个单词连接在一起），首字母大写的命名法只用于异常名或者内部的常量。

Exception Names 异常名

因为异常一般都是类，所有类的命名方法在这里也适用。然而，你需要在异常名后面加上“Error”后缀（如果异常确实是一个错误）

Global Variable Names 全局变量名

（我们希望这一类变量只在模块内部使用。）约定和函数命名规则一样。 通过 from M import * 导入的模块应该使用all机制去防止内部的接口对外暴露，或者使用在全局变量前加下划线的方式（表明这些全局变量是模块内非公有）。

Function Names 函数名

函数名应该小写，如果想提高可读性可以用下划线分隔。 大小写混合仅在为了兼容原来主要以大小写混合风格的情况下使用（比如 threading.py），保持向后兼容性。

Function and method arguments 函数和方法参数

始终要将 self 作为实例方法的的第一个参数。 始终要将 cls 作为类静态方法的第一个参数。 如果函数的参数名和已有的关键词冲突，在最后加单一下划线比缩写或随意拼写更好。因此 class_ 比 clss 更好。（也许最好用同义词来避免这种冲突）

Method Names and Instance Variables 方法名和实例变量

遵循这样的函数命名规则：使用下划线分隔小写单词以提高可读性。 在非共有方法和实例变量前使用单下划线。
通过双下划线前缀触发
Python的命名转换规则来避免和子类的命名冲突。 Python通过类名对这些命名进行转换：如果类 Foo 有一个叫 __a 的成员变量， 它无法通过 Foo.__a 访问。（执着的用户可以通过 Foo._Foo__a 访问。）一般来说，前缀双下划线用来避免类中的属性命名与子类冲突的情况。 注意：关于__names的用法存在争论（见下文）。

Constants 常量

常量通常定义在模块级，通过下划线分隔的全大写字母命名。例如： MAX_OVERFLOW 和 TOTAL。

Designing for inheritance 继承的设计

始终要考虑到一个类的方法和实例变量（统称：属性）应该是共有还是非共有。如果存在疑问，那就选非共有；因为将一个非共有变量转为共有比反过来更容易。 公共属性是那些与类无关的客户使用的属性，并承诺避免向后不兼容的更改。非共有属性是那些不打算让第三方使用的属性；你不需要承诺非共有属性不会被修改或被删除。 我们不使用“私有（private）”这个说法，是因为在Python中目前还没有真正的私有属性（为了避免大量不必要的常规工作）。 另一种属性作为子类API的一部分（在其他语言中通常被称为“protected”）。有些类是专为继承设计的，用来扩展或者修改类的一部分行为。当设计这样的类时，要谨慎决定哪些属性时公开的，哪些是作为子类的API，哪些只能在基类中使用。 贯彻这样的思想，一下是一些让代码Pythonic的准则：
• 公共属性不应该有前缀下划线。
• 如果公共属性名和关键字冲突，在属性名之后增加一个下划线。这比缩写和随意拼写好很多。（然而，尽管有这样的规则，在作为参数或者变量时，‘cls’是表示‘类’最好的选择，特别是作为类方法的第一个参数。） 注意1：参考之前的类方法参数命名建议
• 对于单一的共有属性数据，最好直接对外暴露它的变量名，而不是通过负责的 存取器（accessor）/突变（mutator） 方法。请记住，如果你发现一个简单的属性需要成长为一个功能行为，那么Python为这种将来会出现的扩展提供了一个简单的途径。在这种情况下，使用属性去隐藏属性数据访问背后的逻辑。 注意1：属性只在new-style类中起作用。 注意2：尽管功能方法对于类似缓存的负面影响比较小，但还是要尽量避免。 注意3：属性标记会让调用者认为开销（相当的）小，避免用属性做开销大的计算。
• 如果你的类打算用来继承的话，并且这个类里有不希望子类使用的属性，就要考虑使用双下划线前缀并且没有后缀下划线的命名方式。这会调用Python的命名转换算法，将类的名字加入到属性名里。这样做可以帮助避免在子类中不小心包含了相同的属性名而产生的冲突。 注意1：只有类名才会整合进属性名，如果子类的属性名和类名和父类都相同，那么你还是会有命名冲突的问题。 注意2：命名转换会在某些场景使用起

Programming Recommendations 编程建议

• 代码应该用不损害其他Python实现的方式去编写（PyPy，Jython，IronPython，Cython，Psyco 等）。 比如，不要依赖于在CPython中高效的内置字符连接语句 a += b 或者 a = a + b。这种优化甚至在CPython中都是脆弱的（它只适用于某些类型）并且没有出现在不使用引用计数的实现中。在性能要求比较高的库中，可以种
”.join() 代替。这可以确保字符关联在不同的实现中都可以以线性时间发生。
• 和像None这样的单例对象进行比较的时候应该始终用 is 或者 is not，永远不要用等号运算符。 另外，如果你在写 if x 的时候，请注意你是否表达的意思是 if x is not None。举个例子，当测试一个默认值为None的变量或者参数是否被设置为其他值的时候。这个其他值应该是在上下文中能成为bool类型false的值。
• 使用 is not 运算符，而不是 not … is 。虽然这两种表达式在功能上完全相同，但前者更易于阅读，所以优先考虑。
• 使用 ”.startswith() 和 ”.endswith() 代替通过字符串切割的方法去检查前缀和后缀。 startswith()和endswith()更干净，出错几率更小。比如：

推荐: if foo.startswith('bar'):
糟糕: if foo[:3] == 'bar':

• 对象类型的比较应该用isinstance()而不是直接比较type。

正确: if isinstance(obj, int):
糟糕: if type(obj) is type(1):

参考

1. PEP 7, Style Guide for C Code, van Rossum ↩
2. Barry’s GNU Mailman style guide http://barry.warsaw.us/software/STYLEGUIDE.txt
3. 挂行缩进是一种类型设置样式，其中除第一行之外，段落中的所有行都缩进。在Python中，这个术语是用来描述一种风格：在被括号括起来的语句中，左括号是这一行最后一个非空格字符，随后括号内的内容每一行进行缩进，直到遇到右括号。 ↩
4. Donald Knuth’s The TeXBook, pages 195 and 196 ↩
5. http://www.wikipedia.com/wiki/CamelCase ↩
6. Typeshed repo https://github.com/python/typeshed ↩
7. Suggested syntax for Python 2.7 and straddling code https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code ↩