分号
- 不要在行尾加分号;
- 也不要用分号将两条语句放在同一行;
行
- 每行长度不超过八十个字符;
- 以下情况除外:
- 长的导入模块语句;
- 注释里的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
- 比如赋值(=), 比较(==, <, >, !=, <>, <=, >=, in, not in, is, is not), 布尔(and, or, not);
- 当=用于指示关键字或者默认参数值时,不要在其两侧使用空格;
def complex(real, imag=0.0): return magic(r=real, i=imag)
- 不要使用空格来垂直对齐多行之间的标记;
注释
- 为了提高可读性,注释应该至少举例代码两个空格的举例;
文档字符串
- 包、模块、类、函数中的第一个语句;
- 结构:
- 使用三重双引号包括在内;
- 首行为以句号、问号、惊叹号结束的概述;
- 空行;
- 剩余部分,与文档字符串第一行的第一个引号对齐;
- 内容:
- 函数的用途;
- 输入输出的详细描述;
- 从以下几个方面对函数以小节的格式进行描述;
- Args:
- 列出每个参数的名字,并在名字后使用一个冒号和一个空格;
- 分隔对该参数的描述.如果描述太长超过了单行80字符,使用2或者4个空格的悬挂缩进(与文件其他部分保持一致);
- 描述应该包括所需的类型和含义;
- 如果一个函数接受*foo(可变长度参数列表)或者**bar (任意关键字参数),应该详细列出*foo和**bar;
- Returns:(或者Yields:用于生成器)
- 描述返回值的类型和语义;
- 如果函数返回None,这一部分可以省略。
- Raises:
- 列出与接口有关的所有异常;
- Args:
- 小节的格式;
- 每节应该以一个标题行开始;标题行以冒号结尾;
- 除标题行外,节的其他内容应被缩进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这样的命名,但现在已经不鼓励这样做,因为如果模块名碰巧和类名一致,这会让人困扰;