Python的编码规范

分号

• 不要在行尾加分号；
• 也不要用分号将两条语句放在同一行；

行

• 每行长度不超过八十个字符；
• 以下情况除外：
  • 长的导入模块语句；
  • 注释里的URL；
• 不要使用反斜杠连接行；
• Python会将圆括号中括号花括号中的行隐式地连接起来；
  • 比如在表达式地外围增加一对额外的额圆括号；

    if (width == 0 and height == 0 and
     color == 'red' and emphasis == 'strong'):
    

  • 也可用于过长地文本字符串；
• 在注释中，如果有必要可以将长地URL放在一行；

括号

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

缩进

• 用四个空格来缩进代码；
• 不要tab和空格混用；
• 对于行连接的情况；
  • 垂直对齐换行的元素；

    //与起始变量对齐
    foo = long_function_name(var_one, var_two,
                             var_three, var_four)
                             
    //字典中与起始值对齐
    foo = {
       long_dictionary_key: value1 +
                            value2,
    

  • 使用四个空格的悬挂式缩进；

    //4个空格缩进，第一行不需要
    foo = long_function_name(
       var_one, var_two, var_three,
       var_four)
    

    //字典中4个空格缩进
    foo = {
        long_dictionary_key:
            long_dictionary_value,
       ...
    }
    

空行

• 顶级定义之间空两行；
  • 函数定义、类定义；
• 方法定义之间空一行；
  • 方法定义、类定义与第一个方法之间；

空格

• 括号内不要有空格；
• 不要在冒号、逗号、分号前面加空格，在其后加；
• 参数列表、索引或切片的左括号前不应有空格；

  dict['key'] = list[index]
  

• 二元操作符两边各有一个空格；
  • 比如赋值(=), 比较(==, <, >, !=, <>, <=, >=, in, not in, is, is not), 布尔(and, or, not)；

    x == 1
    

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

  def complex(real, imag=0.0): return magic(r=real, i=imag)
  

• 不要使用空格来垂直对齐多行之间的标记；

注释

• 为了提高可读性，注释应该至少举例代码两个空格的举例；

文档字符串

• 包、模块、类、函数中的第一个语句；
• 结构：
  • 使用三重双引号包括在内；
  • 首行为以句号、问号、惊叹号结束的概述；
  • 空行；
  • 剩余部分，与文档字符串第一行的第一个引号对齐；
• 内容：
  • 函数的用途；
  • 输入输出的详细描述；
  • 从以下几个方面对函数以小节的格式进行描述；
    • Args：
      • 列出每个参数的名字，并在名字后使用一个冒号和一个空格；
      • 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进（与文件其他部分保持一致）；
      • 描述应该包括所需的类型和含义；
      • 如果一个函数接受*foo（可变长度参数列表）或者**bar （任意关键字参数），应该详细列出*foo和**bar；
    • Returns：（或者Yields：用于生成器）
      • 描述返回值的类型和语义；
      • 如果函数返回None，这一部分可以省略。
    • Raises：
      • 列出与接口有关的所有异常；
  • 小节的格式；
    • 每节应该以一个标题行开始；标题行以冒号结尾；
    • 除标题行外，节的其他内容应被缩进2个空格；

对于函数、方法及生成器

• 必须要有文档字符串，除非；
  • 外部不可见；
  • 非常短小；
  • 简单明了；
• 对于复杂的语句，应在代码旁边加注释；

对于类

• 在其文档字符串中，如果类有公共属性（Attributes）,那么文档中应当有一个小节用于描述公有属性；

块注释与行注释

• 对于复杂操作，在其操作开始前写若干行注释；
• 对于非一目了然的代码，在其行尾添加注释；

类

• 如果一个类不继承自其它类，就显式的从object继承；
• 嵌套类也一样。

  class SampleClass(object):
      pass
           
  class OuterClass(object):
      class InnerClass(object):
           pass
  

字符串

• 避免在循环中使用+或者+=操作符来累加字符串；
  • 会创建不必要的临时对象，导致运行时间非线性而是二次方增加；
  • 使用列表，将字符串加入列表中，在循环结束后用.join方法连接列表元素；
• 同一文件下字符串引号应该一致；
• 多行字符串使用三重双引号

文件

• 在文件和sockets结束时显式地关闭操作；
  • 推荐使用“with”语句来管理文件；
  • 不支持with语句的对象，使用contextlib.closing()；

TODO注释

• 为临时代码使用TODO注释；
• 语法结构：

  # TODO(邮件地址): 语句解释.
  

导入格式

• 每个导入应该单独占一行；
• 导入总应该放在文件顶部，位于模块注释和文档字符串之后，模块全局变量和常量之前；
• 导入应该按照从最通用到最不通用的顺序分组：
  • 标准库导入；
  • 第三方库导入；
  • 应用程序指定导入；
• 每种分组中，应该根据每个模块的完整包路径按字典序排序, 忽略大小写；

语句

• 通常每个语句应该独占一行；
• 如果测试结果与测试语句在一行放得下，可以放在同一行；

命名

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

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