1、注意事项
(1)文档仅适用于基于Python主要发行版本的标准库。
(2)文档中的约定应基于现实考虑灵活处理,根据自身需求和团队其他成员的阅读习惯做适当调整。
(3)若遵循文档中的规范使得代码可读性更差,或者因不符合个人习惯会造成代码错误,应适当采用。
(4)已完成的代码未很好的遵循文档规范,不建议重新修改。
2、代码布局
2.1、Indentation 缩进
-
每一级缩进使用4个空格。
-
续行应该与其包裹元素对齐,要么使用圆括号、方括号和花括号内的隐式行连接来垂直对齐,要么使用挂行缩进对齐。
-
当使用挂行缩进时,应该考虑到第一行不应该有参数,以及使用缩进以区分自己是续行。
推荐:
# 与左括号对齐(垂直对齐) 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) # 挂行缩进应该再换一行 foo = long_function_name( var_one, var_two, var_three, var_four)
不推荐:
# 没有使用垂直对齐时,禁止把参数放在第一行 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)
-
如果两个字符的关键字(这里为if)加上一个空格和一个左括号可以组合成为一个4空格的缩进。可能会造成if语句内部代码和判断条件视觉上的冲突,一般有如下几种处理方式。
# 没有额外的缩进,无法区分函数头和代码块 if (this_is_one_thing and that_is_another_thing): do_something() # 增加一个注释,在能提供语法高亮的编辑器中可以有一些区分 if (this_is_one_thing and that_is_another_thing): # Since both conditions are true, we can frobnicate. do_something() # 在条件判断的语句添加额外的缩进 if (this_is_one_thing and that_is_another_thing): do_something()
-
在多行结构中的大括号/中括号/小括号的右括号可以与内容对齐单独起一行作为最后一行的第一个字符:
my_list = [ 1, 2, 3, 4, 5, 6 ] result = some_function_that_takes_arguments( 'a', 'b', 'c', 'd', 'e', 'f' )
2.2、关于空格和制表符
(1)首选的缩进方式应选择空格。
(2)制表符只能用于与同样使用制表符缩进的代码保持一致。
(3)Python3不允许混合使用空格和制表符。
(4)Python2开发的项目代码中应将混合使用空格和制表符的内容统一修改为空格。
(5)用命令行调用Python2项目代码时,建议加入-t
或者-tt
选项。加入-t
会在混合使用制表符和空格的位置发出警告,加入-tt
这些警告会变成错误,给予提示。
2.3、行的最大长度
(1)所有行限制的最大字符数为79个字符。
(2)对于结构限制较少的长文本块(文档字符或者注释),行长度应限制为72个字符。
(3)限制所需的编辑器窗口宽度(控制行长度)可以使多个文件并排打开,并且在相邻列中显示两个版本的代码审阅工具时效果更好。
(4)如果代码主要由一个团队维护,且同意使用更长的行宽,则可以把长度从80增加到100(或99),但是注释和文档字符仍然应保持72个字符换行。
(5)Python标准库相对保守,需要将行宽限制在79个字符(文档字符和注释限制在72个字符)。
(6)较长行的代码首选的换行方式是在括号、方括号和大括号内使用Python的隐式换行,不应优先使用反斜杠来换行。
(7)多个with
(此外还有:long
、multiple
等)状态语句下句子较长,不能使用隐式换行,应使用反斜杠换行:
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())
2.4、二元运算符处的换行
-
以往,二元运算符处要求在运算符后换行,但这会影响可读性。为提高代码的可读性,规定段落中的公式应在二元运算符之前换行。
# 推荐:运算符和操作数很容易进行匹配,逻辑更清晰 income = (gross_wages + taxable_interest + (dividends - qualified_dividends) - ira_deduction - student_loan_interest)
2.5、空行
(1)顶层函数和类的定义,前后应用两个空行隔开。
(2)类里的方法定义用一个空行隔开。
(3)相关的功能组可以用额外的空行隔开,相关的单行代码之间的空白行可以省略。
(4)应尽量避免在函数中使用空行来区分逻辑段。
2.6、源文件编码
(1)Python核心发布版本中的代码总是以UTF-8格式编码(或者在Python2中用ASCII编码)。
(2)标准库中非默认的