python风格规范

python

参考

python风格规范

未掌握的风格

访问控制

• 在Python中, 对于琐碎又不太重要的访问函数, 你应该直接使用公有变量来取代它们, 这样可以避免额外的函数调用开销. 当添加更多功能时, 你可以用属性(property)来保持语法的一致性.
• 另一方面, 如果访问更复杂, 或者变量的访问开销很显著, 那么你应该使用像 get_foo() 和 set_foo() 这样的函数调用.
• 如果之前的代码行为允许通过属性(property)访问 , 那么就不要将新的访问函数与属性绑定. 这样, 任何试图通过老方法访问变量的代码就没法运行, 使用者也就会意识到复杂性发生了变化.

括号

宁缺毋滥的使用括号。

• 除非是用于实现行连接, 否则不要在返回语句或条件语句中使用括号.
• 在元组两边使用括号是可以的.

空行

• 顶级定义之间空两行，比如函数或者类定义
• 方法之间空一行。方法定义, 类定义与第一个方法之间, 都应该空一行
• 函数或方法中, 某些地方要是你觉得合适, 就空一行.

空格

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

• 括号内不要有空格.

• 不要在逗号, 分号, 冒号前面加空格, 但应该在它们后面加(除了在行尾).

• 参数列表, 索引或切片的左括号前不应加空格.

• 在二元操作符两边都加上一个空格,

• 至于算术操作符两边的空格该如何使用, 需要你自己好好判断. 不过两侧务必要保持一致.

• 当’=’用于指示关键字参数或默认参数值时, 不要在其两侧使用空格.

• 不要用空格来垂直对齐多行间的标记, 因为这会成为维护的负担(适用于:, #, =等)

  foo = 1000  # comment
  long_name = 2  # comment that should not be aligned

命名

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.

• 应避免的名称

  1. 单字符名称, 除了计数器和迭代器.
  2. 包/模块名中的连字符(-)
  3. 双下划线开头并结尾的名称(Python保留, 例如__init__)

• 命名规定

  1. 所谓”内部(Internal)”表示仅模块内可用, 或者, 在类内是保护或私有的.
  2. 用单下划线(_)开头表示模块变量或函数是protected的(使用import * from时不会包含).
  3. 用双下划线(__)开头的实例变量或方法表示类内私有.
  4. 将相关的类和顶级函数放在同一个模块里. 不像Java, 没必要限制一个类一个模块.
  5. 对类名使用大写字母开头的单词(如CapWords, 即Pascal风格), 但是模块名应该用小写加下划线的方式(如lower_with_under.py). 尽管已经有很多现存的模块使用类似于CapWords.py这样的命名, 但现在已经不鼓励这样做, 因为如果模块名碰巧和类名一致, 这会让人困扰.

Python之父Guido推荐的规范

除了类名，异常名，全局或类常量外，其余的都采用小写字母并且以下划线分隔单词的形式

• 模块名：采用小写字母并且以下划线分隔单词的形式
• 包名：采用小写字母并且以下划线分隔单词的形式
• 函数名：采用小写字母并且以下划线分隔单词的形式
• 全局或类变量：采用小写字母并且以下划线分隔单词的形式
• 实例变量：采用小写字母并且以下划线分隔单词的形式
• 方法名：采用小写字母并且以下划线分隔单词的形式
• 函数、方法参数：采用小写字母并且以下划线分隔单词的形式

• 局部变量：采用小写字母并且以下划线分隔单词的形式

• 类名：采用每个单词首字母大写的方式

• 异常名：采用每个单词首字母大写的方式

• 全局或者类常量：全部使用大写字母，并且以下划线分隔单词

已经掌握的风格

分号

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

行长度

• 每行不超过80个字符

• 不要使用反斜杠连接行.

• Python会将 圆括号, 中括号和花括号中的行隐式的连接起来 , 你可以利用这个特点. 如果需要, 你可以在表达式外围增加一对额外的圆括号.

  foo_bar(self, width, height, color='black', design=None, x='foo',
             emphasis=None, highlight=0)
  if (width == 0 and height == 0 and
       color == 'red' and emphasis == 'strong'):

• 如果一个文本字符串在一行放不下, 可以使用圆括号来实现隐式行连接

  x = ('This will build a very long long '
     'long long long long long long string')

• 在注释中，如果必要，将长的URL放在一行上。

  http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html

缩进

用4个空格来缩进代码

• 绝对不要用tab, 也不要tab和空格混用.
• 对于行连接的情况, 你应该要么垂直对齐换行的元素(见 行长度 部分的示例), 或者使用4空格的悬挂式缩进

shebang

大部分.py文件不必以#!作为文件的开始. 但是程序的main文件应该以 #!/usr/bin/python2或者 #!/usr/bin/python3开始.

注释

文档字符串

文档字符串是包, 模块, 类或函数里的第一个语句. 这些字符串可以通过对象的__doc__成员被自动提取, 并且被pydoc所用.

一个文档字符串应该这样组织: 首先是一行以句号, 问号或惊叹号结尾的概述(或者该文档字符串单纯只有一行). 接着是一个空行. 接着是文档字符串剩下的部分, 它应该与文档字符串的第一行的第一个引号对齐.

对模块的注释

每个文件应该包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD, LGPL, GPL), 选择合适的样板.

函数和方法的注释

• 函数指的是函数, 方法, 以及生成器.一个函数必须要有文档字符串。
• 当一个函数满足三个条件时，可以不需要文档字符串：1. 外部不可见，2 非常短小， 3， 简单明了。
• 文档字符串应该包含函数做什么, 以及输入和输出的详细描述.

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.
    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.
    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.
    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:
        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}
        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.
    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

• 每节应该以一个标题行开始. 标题行以冒号结尾. 除标题行外, 节的其他内容应被缩进2个空格.

• Args:

  列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致). 描述应该包括所需的类型和含义. 如果一个函数接受*foo(可变长度参数列表)或者**bar (任意关键字参数), 应该详细列出*foo和**bar.

• Return:

  描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略.

• Raise:

  列出与接口有关的所有异常.

类的注释

类应该在其定义下有一个用于描述该类的文档字符串. 如果你的类有公共属性(Attributes), 那么文档中应该有一个属性(Attributes)段. 并且应该遵守和函数参数相同的格式.

class SampleClass(object):
    """Summary of class here.
    Longer class information....
    Longer class information....
    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

什么时候需要添加注释

最需要写注释的是代码中那些技巧性的部分. 如果你在下次 代码审查 的时候必须解释一下, 那么你应该现在就给它写注释.

• 块注释：

  对于复杂的操作, 应该在其操作开始前写上若干行注释. 如一个逻辑控制块等

• 行注释

  对于不是一目了然的单行代码, 应在其行尾添加注释.

• 为了提高可读性, 注释应该至少离开代码2个空格.

• 另一方面, 绝不要描述代码. 假设阅读代码的人比你更懂Python, 他只是不知道你的代码要做什么.

类

如果一个类不继承自其它类, 就显式的从object继承. 嵌套类也一样.

class SampleClass(object):

字符串

即使参数都是字符串, 使用%操作符或者格式化方法格式化字符串. 不过也不能一概而论, 你需要在+和%之间好好判定.

x = '%s, %s!' % (imperative, expletive)
     x = '{}, {}!'.format(imperative, expletive)

文件和sockets

TODO注释

为临时代码使用TODO注释, 它是一种短期解决方案. TODO 自然表示需要做而未做的一些待完成的事项，有助于事后的检索，以及对整体项目做进一步的修改迭代。

• 1. 开头处包含”TODO”字符串
  2. 紧跟着是用括号括起来的你的名字, email地址或其它标识符.
  3. 一个可选的冒号.
  4. 一行注释, 解释要做什么.

• # TODO(kl@gmail.com): Use a "*" here for string repetition.
  # TODO(Zeke) Change this to use relations.

• 如果你的TODO是”将来做某事”的形式, 那么请确保你包含了一个指定的日期(“2009年11月解决”)或者一个特定的事件(“等到所有的客户都可以处理XML请求就移除这些代码”).

ATOM插件：todo-show.

导入格式

• 每个导入应该独占一行
• 导入总应该放在文件顶部, 位于模块注释和文档字符串之后, 模块全局变量和常量之前.

• 导入应该以以下方式分组：

  1. 标准库导入
  2. 第三方库导入
  3. 应用程序导入

• 每种分组中, 应该根据每个模块的完整包路径按字典序排序, 忽略大小写.

语句

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

Main

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

def main():
      ...
if __name__ == '__main__':
    main()