Python代码规范：PEP 8对多行注释和Docstring的建议

晚来风

发布时间：2026-10-29 | 5人浏览过

原创

深入解析Python官方代码规范PEP 8与PEP 257中关于多行注释（Block Comments）与文档字符串（Docstring）的核心建议，厘清底层机制、格式规范、排版要求与选型决策。

在编写 Python 代码时，许多开发者容易将“多行注释”与“文档字符串（Docstring）”混为一谈，甚至习惯用三引号随意包裹一段文字来充当代码说明。根据 Python 官方的 PEP 8 代码风格指南（以及与其互为补充的 PEP 257 文档字符串规范），注释与 Docstring 具有完全不同的定位、处理机制与语法要求：多行注释始终面向代码维护者，解释内部实现的“原因”（Why），语法上必须由以 # 开头的行构成；而 Docstring 面向接口调用者，说明组件的“功能与用法”（What & How），必须使用三双引号 """ 并放置在特定对象的首部。理解并遵守这两套规则，是写出干净、专业且符合社区共识的 Python 代码的基本功。

一、底层机制：为什么注释与 Docstring 不能混用

Python 解释器对待普通注释和未赋值字符串字面量的处理逻辑存在本质差别。明确这一机制，是正确选择两者形态的前提。

当 Python 词法分析器（Tokenizer）扫描源代码时，任何以 # 开始的内容都会在语法分析之前被直接剥离，完全不会生成抽象语法树（AST）节点，也不会产生字节码。这意味着无论你在多行注释中写了什么，运行时都无法获取这些信息，内存占用也是严格为零。

相反，放置在模块、类、函数或方法定义第一行的三引号字符串，会被编译器识别为该作用域的专属说明，进而存入代码对象的常量表（co_consts）中，并在运行时自动赋值给目标对象的 __doc__ 属性。诸如 help() 函数、IDE 代码补全悬浮窗以及 Sphinx 等自动化文档工具，都是依赖 __doc__ 属性来提取信息的。

Python代码规范：PEP 8对多行注释和Docstring的建议 — 图 1：多行注释与 Docstring 在编译执行全流程中的生命周期差异

二、PEP 8 对多行注释（Block Comments）的具体建议

多行注释在 PEP 8 中被称为“块注释（Block Comments）”。当单行说明不足以阐释复杂业务流程或特殊技术方案时，就需要编写多行块注释。PEP 8 对此给出了明确的版式和语法约束：

1. 格式约束：每一行必须以 `#` 开头

PEP 8 规定，块注释通常由一个或多个段落组成，每一行都必须以 # 和一个空格开头。即便注释跨越了十行，也不能使用三引号省略开头的井号。

2. 段落隔离：使用单独包含 `#` 的空行

如果多行注释较长需要划分段落，段落之间不能直接留出纯粹的物理空白行，而必须保留一个仅包含 # 字符（不含任何额外文字）的行作为段落分隔。这样能保证整段注释在视觉上形成连续的缩进块，避免与周围的代码产生视觉割裂。

3. 缩进层级：严格与被解释代码对齐

块注释的缩进级别必须与其所解释的代码保持完全一致。例如，在缩进为 4 个空格的函数体内解释一段 for 循环，注释的 # 前面同样必须有 4 个空格的缩进。

4. 行宽上限：推荐控制在 72 个字符以内

PEP 8 建议代码本身的最大行宽为 79 个字符，但对于纯文本性质的文档字符串与块注释，强烈推荐将单行宽度限制在 72 个字符以内。这是为了确保开发者在左右分屏查看代码、或者在终端查看 Git 补丁（Diff）时，长注释不会发生难看的自动折行。

# 推荐的 PEP 8 块注释示例
def process_transactions(transactions, fee_rate):
    # 针对跨周期交易执行双重对账核验。
    # 由于上游结算接口可能存在最多 500ms 的网络抖动，
    # 此处采用指数退避重试策略，避免瞬时并发击穿重试队列。
    #
    # 注意：如果 fee_rate 为零，系统将跳过免息通道的验证环节，
    # 该行为属于特定渠道协议，不可随意更改。
    results = []
    for tx in transactions:
        results.append(reconcile_single(tx, fee_rate))
    return results

为什么不能用三引号字符串代替多行块注释？

很多开发者为了偷懒，用 """ 说明文字 """ 包裹在函数内部充当普通多行注释。虽然 Python 语法允许存在未赋值的字面量表达式，但 PEP 8 明确反对这种做法。原因在于：它破坏了语意边界，代码静态分析工具（如 Linter）可能会将其误判为格式错误的 Docstring，且未引用的字符串仍会进入字节码常量区，平白增加无意义的字节码开销。

三、PEP 8 与 PEP 257 对 Docstring 的规范建议

文档字符串是 Python 的一级语言特性。PEP 8 确立了 Docstring 的基本编写态度，而具体排版与语法细节则由专门的 PEP 257（Docstring Conventions） 详细定义。

1. 引号规范：始终坚持三双引号 `"""`

PEP 8 与 PEP 257 明确要求：所有的 Docstring 必须始终使用三双引号 """，即便整个 Docstring 只有一行，也不要使用三单引号 ''' 或普通单双引号。这保证了整套代码库风格的高度统一。

2. 单行 Docstring（One-line Docstrings）

当函数非常简单、功能极其直观时，可以使用单行 Docstring。单行 Docstring 必须遵循以下要点：

开头与结尾的三引号必须在同一行；
使用祈使句式（如“返回某对象”而非“用于返回某对象”），句首字母大写（英文）或符合中文语法，句末必须有句号；
不要单纯机械复述参数和函数名（如 def add(a, b): """Add a and b.""" 属于废话注释），应指明关键边界或特性。

def square_root(value: float) -> float:
    """计算非负浮点数的算术平方根，负数输入将抛出 ValueError。"""
    if value < 0:
        raise ValueError("输入值必须大于等于0")
    return value ** 0.5

3. 多行 Docstring（Multi-line Docstrings）的五段式标准结构

对于具备参数、返回值或副作用的公开接口，多行 Docstring 遵循严格的排版版式：

第一行（摘要行）：必须是简明扼要的一句话摘要，以句号结束；
第二行（空行）：必须留出一行空行。这是为了让自动化工具（如 pydoc）能够精准切分摘要与详细内容，绝不可将详情直接紧贴在第一行下方；
第三部分（详细描述）：从第三行开始展开段落，详细解释调用契约、内部假设或副作用；
第四部分（结构化参数说明）：按规范列出 Args、Returns、Raises 等模块（常见的有 Google 风格或 Sphinx 风格）；
闭合三引号独立成行：多行 Docstring 的结束三引号 """ 必须单独占一行，并且与其第一行的缩进严格对齐。

四、实践指南：何时使用注释？何时使用 Docstring？

在日常开发中，面对一段待说明的内容，可以通过明确的逻辑路径快速判断应当使用何种形式：

第一步：判定目标受众。如果这段文字是写给“调用该接口或模块的外部人员”看的，告诉他们如何正确使用、传什么参数，它必须是 Docstring。如果这段文字是写给“维护或者修改这段具体实现的内部人员”看的，解释代码为什么这样写、有什么特殊考量，它必须是注释。
第二步：判定对象可见性。所有公共模块（Public Modules）、导出的类（Classes）、公共函数（Functions）以及公开 API 方法，都必须有 Docstring。对于私有方法（以单下划线 _ 开头），PEP 8 并不强制要求编写 Docstring，但依然建议通过简要说明阐述其职责。
第三步：判定文字跨度与位置。若为单句实现说明，且紧贴代码行右侧，采用行内注释（代码与 # 之间必须至少有两个空格）；若说明涉及复杂的业务因果或多行算法，则采用由 # 开头的多行块注释。

五、常见反模式与避坑清单

在实际项目审查（Code Review）中，以下几类不规范现象最为普遍，应当在日常编码中刻意规避：

反模式 1：用三引号注释掉废弃的代码块

在调试过程中，不少人喜欢直接用 """ 将十几行代码包起来进行“临时注释”。这在提交到版本控制仓库（Git）时是极其不规范的。未绑定的三引号不是合法的代码废弃手段，应当使用编辑器快捷键批量添加 # 注释，或者直接删除废弃代码——版本控制系统本身就拥有完整的历史记录。

反模式 2：多行 Docstring 结束引号紧贴文字

# 错误示例：结束三引号未独立成行
def parse_payload(payload):
    """解析网络报文的主体内容。
    
    参数 payload 为原始字节流。"""
    pass

# 正确规范：结束三引号独占一行
def parse_payload(payload):
    """解析网络报文的主体内容。

    参数 payload 为原始字节流。
    """
    pass

反模式 3：在 Docstring 中省略第二行的空行

如果在多行 Docstring 中直接将长篇说明写在摘要行的下一行而没有空行隔开，类似 Sphinx 等文档解析器会将两行合并为一段，导致生成的 API 目录索引出现排版混乱。

反模式 4：注释与代码事实脱节

PEP 8 专门强调了一句名言：“与代码矛盾的注释比没有注释还要糟糕”。每当重构或修改函数逻辑时，必须第一优先级同步更新其 Docstring 与相关块注释，永远不要留下具有误导性的陈旧说明。

六、工程落地：如何自动化保障规范执行

在团队协作中，完全依靠人工 Code Review 检查空格与三引号往往耗时耗力。可以借助 Python 生态成熟的静态检查工具链实现自动化约束：

flake8 与 flake8-docstrings：结合 pydocstyle 规则集，能够在提交代码时自动检测 Docstring 是否缺失第一行摘要后的空行、是否使用了正确的三双引号等（如 D209 规则专门检查多行文档字符串的闭合三引号是否独占一行）。
Ruff：作为现代高性能 linter，Ruff 原生内置了绝大部分 D 系列（pydocstyle）规则，毫秒级即可扫描出未换行的 Docstring 结束引号或不合规的单行注释。
Black / Blue 格式化工具：虽然格式化工具不会替你写注释内容，但它们会自动规范代码与行内注释之间的空格间距（保证至少有两个空格）。

遵循 PEP 8 与 PEP 257 并非死板的教条，而是让 Python 代码具备高度自解释性与一致性的最佳实践。在写下下一行说明文字之前，先明确它是写给“调用者”还是“维护者”，再赋予其标准的形态，就能让项目文档与代码逻辑始终保持清晰、专业与严谨。