摘要
本文给出主Python版本标准库的编码约定。CPython的C代码风格参见PEP7。本文和PEP 257 文档字符串标准改编自Guido最初的《Python Style Guide》, 并增加了Barry的GNU Mailman Coding Style Guide的部分内容。本文会随着语言改变等而改变。许多项目都有自己的编码风格指南,冲突时自己的指南为准。
本文给出主Python版本标准库的编码约定。CPython的C代码风格参见PEP7。
本文和PEP 257 文档字符串标准改编自Guido最初的《Python Style Guide》, 并增加了Barry的GNU Mailman Coding Style Guide的部分内容。
本文会随着语言改变等而改变。
许多项目都有自己的编码风格指南,冲突时自己的指南为准。
一致性考虑
Guido的关键点之一是:代码更多是用来读而不是写。本指南旨在改善Python代码的可读性,即PEP 20所说的"可读性计数"(Readability counts)。
风格指南强调一致性。项目、模块或函数保持一致都很重要。
最重要的是知道何时不一致, 有时风格指南并不适用。当有疑惑时运用你的最佳判断,参考其他例子并多问!
特别注意:不要因为遵守本PEP而破坏向后兼容性!
部分可以违背指南情况:
- 遵循指南会降低可读性。
- 与周围其他代码不一致。
- 代码在引入指南完成,暂时没有理由修改。
- 旧版本兼容。
代码布局
缩进
每级缩进用4个空格。
括号中使用垂直隐式缩进或使用悬挂缩进。后者应该注意第一行要没有参数,后续行要有缩进。
- Yes
# 对准左括号
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)
- No
# 不使用垂直对齐时,第一行不能有参数。
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)
4个空格的规则是对续行可选的。
# 悬挂缩进不一定是4个空格
foo = long_function_name(
var_one, var_two,
var_three, var_four)
if语句跨行时,两个字符关键字(比如if)加上一个空格,再加上左括号构成了很好的缩进。后续行暂时没有规定,至少有如下三种格式,建议使用第3种。
# 没有额外缩进,不是很好看,个人不推荐.
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()
# 额外添加缩进,推荐。
# Add some extra indentation on the conditional continuation line.
if (this_is_one_thing
and that_is_another_thing):
do_something()
右边括号也可以另起一行。有两种格式,建议第2种。
# 右括号不回退,个人不推荐
my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)
# 右括号回退
my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)
空格或Tab?
- 空格是首选的缩进方法。
- Tab仅仅在已经使用tab缩进的代码中为了保持一致性而使用。
- Python 3中不允许混合使用Tab和空格缩进。
- Python 2的包含空格与Tab和空格缩进的应该全部转为空格缩进。
Python2命令行解释器使用-t选项时有非法混合Tab和空格的情况会告警。当使用-tt警告提升为错误。强烈推荐这些选项!另外个人推荐pep8和autopep8模块。
最大行宽
限制所有行的最大行宽为79字符。
文本长块,比如文档字符串或注释,行长度应限制为72个字符。
多数工具默认的续行功能会破坏代码结构,使它更难理解,不推荐使用。但是超过80个字符加以提醒是必要的。一些工具可能根本不具备动态换行功能。
一些团队强烈希望更长的行宽。如果能达成一致,可以从从80提高到100个字符(最多99个字符)增加了标称线的长度,不过依旧建议文档字符串和注释保持在72的长度。
Python标准库比较保守,限制行宽79个字符(文档字符串/注释72)。
续行的首选方法是使用小括号、中括号和大括号反斜线仍可能在适当的时候。其次是反斜杠。比如with语句中:
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())
类似的还有assert。
注意续行要尽量不影响可读性。比如通常在二元运算符之后续行:
class Rectangle(Blob):
def __init__(self, width, height,
color='black', emphasis=None, highlight=0):
if (width == 0 and