PEP 8 – Python 代码风格指南中文版（一）

引言

本文档提供了构成Python主分发版中标准库的Python代码的编码约定。请参阅配套的信息性PEP，该PEP描述了Python C实现中C代码的风格指南。

本文档和PEP 257（Docstring约定）改编自Guido最初的Python风格指南文章，并添加了Barry风格指南[2]中的一些内容。

随着新约定的识别和语言本身变化导致的旧约定变得过时，此风格指南会随时间不断发展。

许多项目都有自己的编码风格指南。在出现任何冲突的情况下，特定项目的指南将优先于该项目的其他指南。

愚蠢的一致性是小脑筋的妖怪（盲目追求一致性是小智者的陷阱）

Guido的一个关键见解是，代码的阅读频率远高于编写频率。这里提供的指南旨在提高代码的可读性，并使Python代码在广泛范围内保持一致。正如PEP 20所说，“可读性很重要”。

风格指南是关于一致性的。与本风格指南的一致性很重要。项目内部的一致性更为重要。一个模块或函数内部的一致性最为重要。

然而，要知道何时可以不一致——有时风格指南的建议并不适用。如有疑问，请运用你的最佳判断。查看其他示例并决定哪种方式看起来最好。不要犹豫，尽管提问！

特别是：不要为了遵守此PEP而破坏向后兼容性！

忽略特定指南的其他合理原因包括：

1. 应用该指南会使代码可读性降低，即使对于那些习惯于阅读遵循此PEP的代码的人来说也是如此。
2. 为了与同样违反指南的周围代码保持一致（可能是出于历史原因）——尽管这也是一个清理他人混乱（以真正的XP风格）的机会。
3. 因为相关代码在引入该指南之前就已经存在，并且没有其他理由去修改它。
4. 当代码需要与不支持风格指南推荐功能的旧版Python保持兼容时。

代码布局

缩进

每个缩进级别使用4个空格。

续行应使用Python在括号、方括号和大括号内的隐式行连接，将包装的元素垂直对齐，或使用悬挂缩进[1]。当使用悬挂缩进时，应考虑以下因素：第一行不应有参数，并且应使用进一步的缩进以明确区分其为续行：

# 正确的:
# 与开括号对齐.
foo = long_function_name(var_one, var_two,
                            var_three, var_four)
# 添加4个空格（额外的缩进级别）以区分参数与其他内容.
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)

对于续行，使用4个空格的规则是可选的。

可选项：

# 悬挂缩进可能不使用4个空格进行缩进
foo = long_function_name(
  var_one, var_two,
  var_three, var_four)

当 if 语句的条件部分很长而需要跨越多行书写时，值得注意的是，由两个字符的关键字（即“if” ），加上一个空格，再加上一个左括号组成的组合，为随后多行条件语句的每一行创建了一个自然的4个空格缩进。这可能会在视觉上与嵌套在 if 语句内部的代码块（该代码块也会自然地缩进4个空格）产生冲突。PEP没有明确表明如何（或是否）进一步从视觉上区分这样的条件行与 if 语句内部的嵌套代码块。在这种情况下，可接受的选项包括但不限于：

# 不添加不必要的额外缩进.
if (this_is_one_thing and
    that_is_another_thing):
    do_something()


# 添加一个注释，这将在支持语法高亮或具有代码结构显示功能的编辑器中帮助# 区分代码的不同部分。
if (this_is_one_thing and
    that_is_another_thing):
    # 由于两个条件都为真，我们可以执行frobnicate操作.
    do_something()


# 在条件语句的续行上增加一些额外的缩进（注意 and 的位置）。
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',
    )

或者，它（闭合括号）可以与开始多行结构的那一行的第一个字符对齐，如下所示：

my_list = [
    1, 2, 3,
    4, 5, 6,
]

result = some_function_that_takes_arguments(
    'a', 'b', 'c',
    'd', 'e', 'f',
)

     相关文章：

PEP 8 – Python 代码风格指南中文版（一）

PEP 8 – Python 代码风格指南中文版（二）

PEP 8 – Python 代码风格指南中文版（三）

PEP 8 – Python 代码风格指南中文版（四）

PEP 8 – Python 代码风格指南中文版（五）

PEP 8 – Python 代码风格指南中文版（六）

PEP 8 – Python 代码风格指南中文版（七）

PEP 8 – Python 代码风格指南中文版（八）

PEP 8 – Python 代码风格指南中文版（九）