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

何时使用尾随逗号

尾随逗号通常是可选的，但在创建一个只有一个元素的元组时是必须的。为了清晰起见，建议使用（技术上多余的）括号将其包围起来：

# 正确的:
FILES = ('setup.cfg',)

# 错误的:
FILES = 'setup.cfg',

当尾随逗号是多余的时候，在使用版本控制系统时，或者当预期值列表、参数或导入项会随着时间的推移而扩展时，它们通常很有帮助。这种模式的做法是将每个值（等）放在一行上，并始终添加一个尾随逗号，然后在下一行添加闭合的括号/方括号/花括号。但是，在闭合分隔符所在行添加尾随逗号是没有意义的（除了上面提到的单元素元组的情况）：

# 正确的:
FILES = [
    'setup.cfg',
    'tox.ini',
    ]initialize(FILES,
           error=True,
           )

# 错误的:
FILES = ['setup.cfg', 'tox.ini',]initialize(FILES, error=True,)

注释

与代码相矛盾的注释比没有注释更糟糕。当代码发生变化时，务必优先更新注释！

注释应该是完整的句子。第一个单词应该大写，除非它是一个以小写字母开头的标识符（永远不要更改标识符的大小写！）

块注释通常由一个或多个由完整句子组成的段落组成，每个句子以句号结尾。

在多句注释中，除了最后一句之外，每句句末的句号后应使用一个或两个空格。

请确保您的注释清晰易懂，以便其他使用您所用语言的人能够理解。

来自非英语国家的Python程序员：请用英语编写注释，除非您100%确定代码绝不会被不懂您母语的人阅读。

块注释

块注释通常适用于它们之后的一些（或全部）代码，并且与这些代码的缩进级别相同。块注释的每一行都以一个#和一个空格开始（除非它是注释内部的缩进文本）。块注释内部的段落由包含单个#的行分隔。

行内注释

谨慎使用行内注释。

行内注释是与语句位于同一行的注释。行内注释应与语句之间至少有两个空格的分隔。它们应该以#和一个空格开头。

如果行内注释陈述的是显而易见的内容，那么它们是不必要的，并且实际上会分散注意力。不要这样做：

x = x + 1                 # Increment x

但是有时候，这样做是有用的：

x = x + 1                 # Compensate for border

文档字符串

编写良好文档字符串（也称为“docstrings”）的约定在PEP 257中得到了永恒的传承。

• 为所有公共模块、函数、类和方法编写文档字符串。对于非公共方法，文档字符串不是必需的，但你应该有一个注释来描述该方法的作用。这个注释应该出现在def语句之后。
• PEP 257描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的三个双引号（"""）应该独占一行：

"""Return a foobang

Optional plotz says to frobnicate the bizbaz first.
"""

• 对于单行文档字符串，请将结束的三个双引号（"""）保持在同一行：

"""Return an ex-parrot."""

命名约定

Python库的命名约定有点混乱，因此我们无法完全保持一致——尽管如此，以下是当前推荐的命名标准。新的模块和包（包括第三方框架）应该按照这些标准编写，但如果现有库采用了不同的风格，则内部一致性是首选。

首要原则

作为API的公共部分对用户可见的名称应遵循反映用法而非实现的约定。

描述性：命名风格

存在许多不同的命名风格。能够独立于它们的用途来识别所使用的命名风格是有帮助的。

以下命名风格通常有所区别：

• b（单个小写字母）
• B（单个大写字母）
• lowercase（全部小写）
• lower_case_with_underscores（小写字母和下划线）
• UPPERCASE（全部大写）
• UPPER_CASE_WITH_UNDERSCORES（大写字母和下划线）
• CapitalizedWords（大驼峰，或CapWords，或CamelCase——因其字母看起来有起伏而得名[4]）。有时也被称为StudlyCaps。

注意：在使用CapWords中的缩写时，请将缩写的所有字母都大写。因此，HTTPServerError比HttpServerError更好。

• mixedCase（小驼峰，与CapitalizedWords不同，首字母小写！）
• Capitalized_Words_With_Underscores（丑陋！）

还有一种风格是使用简短的唯一前缀来将相关名称组合在一起。在Python中，这种风格使用得不多，但出于完整性考虑，这里还是提一下。例如，os.stat()函数返回一个元组，其项目传统上具有如st_mode、st_size、st_mtime等名称。（这样做是为了强调与POSIX系统调用结构中的字段的对应关系，这对熟悉该结构的程序员有所帮助。）

X11库使用前导X来命名其所有公共函数。在Python中，这种风格通常被认为是不必要的，因为属性和方法名称都以对象作为前缀，而函数名称则以模块名称作为前缀。

此外，还识别以下使用前导或尾随下划线的特殊形式（这些通常可以与任何大小写约定结合使用）：

• _single_leading_underscore（单个前导下划线）：表示“内部使用”的弱指示符。例如，from M import * 不会导入名称以下划线开头的对象。
• single_trailing_underscore_（单个尾随下划线）：按照惯例，用于避免与Python关键字冲突，例如：

tkinter.Toplevel(master, class_='ClassName')

• __double_leading_underscore（双前导下划线）：在命名类属性时，会触发名称改编（在类FooBar内部，__boo会变成_FooBar__boo；见下文）。
• __double_leading_and_trailing_underscore__（双前导和双尾随下划线）：“魔法”对象或属性，存在于用户控制的命名空间中。例如，__init__、__import__或__file__。永远不要自己发明这样的名称；只应按文档说明使用它们。

往期文章：

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

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

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