Python编程规范

作者：cedar（https://www.jianshu.com/writer#/notebooks/28559629/notes/32344372）

---

Python风格规范

1. 不要在行尾加分号，也不要用分号将两条命令放在同一行。

2. 每行不超过80个字符。

   • 2.1 长的导入模块语句和注释里的URL例外。
   • 2.2 不使用反斜杠连接行。
   • 2.3 Python会将圆括号，中括号和花括号中的行隐式的连接起来。
   • 2.4 在注释中，将长的URL放在一行上。

3. 宁缺勿滥的使用括号，除非是用于行连接，否则不要在返回语句或条件语句中使用括号。

4. 用四个空格来缩进代码，不要使用tab，也不要tab和空格混用。对于行连接的情况，应该要么垂直对齐换行的元素或者使用4空格的悬挂式缩进（此时第一行不该有参数）。

5. 空行：顶级定义（函数或者类定义）之间空两行，方法定义之间空一行。

6. 空格：按照标准的排版规范来使用标点两边的空格。

   • 6.1 括号内不要有空格。
   • 6.2 不要在逗号，分号，冒号前边加空格，但应该在后面加
   • 6.3 参数列表，索引或切片的左括号前不应加空格
   • 6.4 在二元操作符两边都加上一个空格，比如赋值(=)，比较(==，<，>，!=，<>，<=，>=，in，not in，is，is not)，布尔(and，or，not)。至于算术操作符两边的空格该如何使用， 需要你自己好好判断。 不过两侧务必要保持一致。
   • 6.5 当’=’用于指示关键字参数或默认参数值时，不要在其两侧使用空格。
   • 6.6 不要用空格来垂直对齐多行间的标记, 因为这会成为维护的负担(适用于：，#，=等)。

7. Shebang：大部分.py文件不必以#!作为文件的开始。根据 PEP-394，程序的main文件应该以 #!/usr/bin/python2或者 #!/usr/bin/python3开始。

8. 注释：确保对模块、函数、方法和行内注释使用正确的风格。

   • 8.1 文档字符串：Python有一种独一无二的的注释方式，使用文档字符串。文档字符串是包， 模块， 类或函数里的第一个语句。这些字符串可以通过对象的__doc__成员被自动提取，并且被pydoc所用。(你可以在你的模块上运行pydoc试一把，看看它长什么样)。我们对文档字符串的惯例是使用三重双引号”“”( PEP-257 )。一个文档字符串应该这样组织：首先是一行以句号，问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行)。接着是一个空行， 接着是文档字符串剩下的部分，它应该与文档字符串的第一行的第一个引号对齐。下面有更多文档字符串的格式化规范。
   • 8.2 模块：每个文件应该包含一个许可样板。根据项目使用的许可（例如，Apache 2.0，BSD，LGPL，GPL），选择合适的样板。
   • 8.3 函数和方法：这里的函数包括函数，方法，以及生成器。一个函数必须要有文档字符串，文档字符串应该包含函数做什么，以及输入和输出的详细描述。通常，不应该描述怎么做，除非是一些复杂的算法。文档字符串应该提供足够的信息，当别人编写代码调用该函数时，他不需要看一行代码，只要看文档字符串就可以了。对于复杂的代码， 在代码旁边加注释会比使用文档字符串更有意义。
   • 8.4 Args：列出每个参数的名字，并在名字后使用一个冒号和一个空格，分隔对该参数的描述。如果描述太长超过了单行80字符，使用2或者4个空格的悬挂缩进(与文件其他部分保持一致)。描述应该包括所需的类型和含义。如果一个函数接受*foo(可变长度参数列表)或者**bar (任意关键字参数)，应该详细列出*foo和**bar。
   • 8.5 Returns(或者Yields：用于生成器)：描述返回值的类型和语义。如果函数返回None，这一部分可以省略。
   • 8.6 Raises：列出与接口有关的所有异常。
   • 8.7 类：类应该在其定义下有一个用于描述该类的文档字符串。如果你的类有公共属性(Attributes)，那么文档中应该有一个属性(Attributes)段。并且应该遵守和函数参数相同的格式。
   • 8.8 块注释和行注释：最需要写注释的是代码中那些技巧性的部分。如果你在下次代码审查的时候必须解释一下，那么你应该现在就给它写注释。对于复杂的操作，应该在其操作开始前写上若干行注释。对于不是一目了然的代码，应在其行尾添加注释。为了提高可读性，注释应该至少离开代码2个空格。

9. 类 ：如果一个类不继承自其它类，就显式的从object继承。嵌套类也一样。继承自 object 是为了使属性(properties)正常工作，并且这样可以保护你的代码，使其不受 PEP-3000 的一个特殊的潜在不兼容性影响。这样做也定义了一些特殊的方法，这些方法实现了对象的默认语义，包括 __new__，__init__，__delattr__，__getattribute__，__setattr__，__hash__，__repr__，and __str__ 。

10. 字符串：

    • 10.1 避免在循环中用+和+=操作符来累加字符串。由于字符串是不可变的，这样做会创建不必要的临时对象，并且导致二次方而不是线性的运行时间。作为替代方案，你可以将每个子串加入列表，然后在循环结束后用 .join 连接列表。(也可以将每个子串写入一个 cStringIO.StringIO 缓存中。)
    • 10.2 在同一个文件中，保持使用字符串引号的一致性。使用单引号’或者双引号”之一用以引用字符串，并在同一文件中沿用。在字符串内可以使用另外一种引号，以避免在字符串中使用。GPyLint已经加入了这一检查。
    • 10.3 为多行字符串使用三重双引号”“”而非三重单引号’‘’。当且仅当项目中使用单引号’来引用字符串时，才可能会使用三重’‘’为非文档字符串的多行字符串来标识引用。 文档字符串必须使用三重双引号”“”。不过要注意，通常用隐式行连接更清晰，因为多行字符串与程序其他部分的缩进方式不一致。

11. 文件和sockets：在文件和sockets结束时，显式的关闭它。推荐使用 “with”语句 以管理文件。对于不支持使用”with”语句的类似文件的对象，使用 contextlib.closing()。

12. TODO注释：为临时代码使用TODO注释，它是一种短期解决方案。

13. 导入格式：每个导入应该独占一行。导入总应该放在文件顶部，位于模块注释和文档字符串之后，模块全局变量和常量之前。导入应该按照从最通用到最不通用的顺序分组。

    • a. 标准库导入
    • b. 第三方库导入
    • c. 应用程序指定导入
    • d. 每种分组中，应该根据每个模块的完整包路径按字典序排序，忽略大小写。

14. 语句：通常每个语句应该独占一行。

15. 访问控制：在Python中，对于琐碎又不太重要的访问函数，你应该直接使用公有变量来取代它们，这样可以避免额外的函数调用开销。当添加更多功能时，你可以用属性(property)来保持语法的一致性。如果访问更复杂，或者变量的访问开销很显著，那么你应该使用像 get_foo() 和 set_foo() 这样的函数调用。如果之前的代码行为允许通过属性(property)访问，那么就不要将新的访问函数与属性绑定。

16. 命名：

    • 16.1 应该避免的名称：单字符名称，除了计数器和迭代器；包/模块名中的连字符(-)；双下划线开头并结尾的名称(Python保留, 例如__init__)。
    • 16.2 命名约定：所谓”内部(Internal)”表示仅模块内可用，或者，在类内是保护或私有的；用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含)。
      用双下划线(__)开头的实例变量或方法表示类内私有。将相关的类和顶级函数放在同一个模块里。不像Java，没必要限制一个类一个模块。对类名使用大写字母开头的单词(如CapWords，即Pascal风格)，但是模块名应该用小写加下划线的方式(如lower_with_under.py)。尽管已经有很多现存的模块使用类似于CapWords.py这样的命名，但现在已经不鼓励这样做，因为如果模块名碰巧和类名一致， 这会让人困扰。

17. Main:即使是一个打算被用作脚本的文件，也应该是可导入的。并且简单的导入不应该导致这个脚本的主功能(main functionality)被执行，这是一种副作用。主功能应该放在一个main()函数中。

引用参考：http://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/