Python中使用三引号'''或"""进行多行注释的正确写法

Alice

发布时间：2026-10-20 | 7人浏览过

原创

在 Python 中，严格的语法定义中并不存在专门的“多行注释关键字”，官方提供的词法注释符号仅有单行井号（#）。然而，开发者普遍使用三单引号（'''）或三双引号（"""）所包裹的多行字符串字面量来充当多行注释。要正确使用这一特性，关键在于理解其背后的编译运行机制、严格遵循当前代码块的缩进对齐规则，并清晰区分“文档字符串（Docstring）”与“纯逻辑注释”的应用边界。

一、核心机制：三引号在Python中的本质与多行注释原理

初学 Python 时，很多读者会将三引号直接等同于 C 语言或 Java 中的 /* ... */ 块注释。但在 Python 的语法解析树（AST）中，三单引号 ''' 与三双引号 """ 产生的是一个“多行字符串常量（Multi-line String Literal）”。

之所以它们能起到多行注释的效果，是因为 Python 解释器在语法设计上允许独立表达式（Expression Statement）单独成行。如果一个字符串字面量既没有被赋值给任何变量，也没有作为参数传递给任何函数，解释器在执行到该位置时，会对其进行求值；而在 CPython 字节码编译阶段，未赋值且非首位文档声明的常数字符串会被优化器直接丢弃，不生成任何操作指令，因此在实际运行中几乎没有性能开销。

然而，根据三引号所在的代码位置不同，Python 对其赋予了截然不同的运行时生命周期：

作为文档字符串（Docstring）：若三引号字符串紧跟在模块、类或函数定义的第一行，解释器会将其编译进该对象的 __doc__ 属性中，常驻内存供 help() 函数及自动化文档工具读取。
作为逻辑代码块注释：若三引号字符串处于可执行语句之间且未赋值，则被视为无副作用的丢弃表达式，在字节码生成后不再占用额外资源。

Python中使用三引号'''或"""进行多行注释的正确写法 — 图 1：Python 解释器处理三引号字符串的两类运行时机制与生命周期对比

二、三引号多行注释的正确书写规范与代码示例

1. 三单引号与三双引号的选用与写法

在语法层面上，三单引号 ''' 与三双引号 """ 的功能完全对称。两者都可以跨越多行书写文本，且在内部包含单引号或双引号时无需频繁转义：

# 示例 1：使用三单引号包裹多行说明
'''
这是一段使用三单引号书写的代码注释。
内部可以自然包含 "双引号" 而不会导致语法解析提前闭合。
'''

# 示例 2：使用三双引号包裹多行说明
"""
这是一段使用三双引号书写的代码注释。
内部可以自然包含 '单引号'，常用于标准文档字符串与长文本说明。
"""

在书写风格上，Python 官方建议（PEP 257）强调：用于表达文档说明时，一律统一采用三双引号 """。而在日常工程中如果使用三引号临时注释普通代码块，则建议保持团队内部统一，避免在同一个文件中混乱混用。

2. 最核心规则：必须严格对齐当前代码块的缩进

这是三引号多行注释最容易引发线上故障的关键点。因为三引号是合法的字符串表达式语法，它必须严格遵循 Python 的缩进语法（Indentation Rules）。

如果三引号出现在函数内部、类定义内部或条件分支循环体内，首个三引号必须与当前逻辑块保持相同空格缩进，绝不能顶格书写，否则直接抛出 IndentationError。

三、常见易错陷阱与进阶注意事项

1. 转义字符与反斜杠解析陷阱

由于三引号包裹的内容本质是字符串，因此字符串内置的转义机制依然有效。例如，如果在多行注释中书写 Windows 文件路径（如 C:\Users\name）或正则表达式时，若末尾包含单个反斜杠 \，反斜杠会转义紧随其后的闭合三引号，造成语法不闭合报错：

# 陷阱：末尾反斜杠转义了引号
"""
注意文件路径：D:\new_workspace\
"""  # 此处末尾的 \ 会转义后面的第一个引号，触发 SyntaxError: EOL while scanning string literal

# 正确写法：使用原始字符串（Raw String）前缀 r
r"""
注意文件路径：D:\new_workspace\
"""

2. 嵌套注释导致的提前截断

当使用三引号临时注释一段已经包含三引号（例如内部有函数的文档字符串）的 Python 代码时，外层的三引号会在遇到内部第一个三引号时立即提前闭合，导致后半段代码暴露为语法错误。

💡 避坑建议：

当被注释的代码块内部包含三双引号 """ 时，外层应选用三单引号 ''' 进行包裹；反之亦然。但如果代码段层次极为复杂，最安全且万无一失的做法是使用编辑器快捷键批量添加 #。

四、工程决策流程：何时用三引号，何时用井号#

在规范的团队项目与长期维护代码中，PEP 8（Python 官方代码风格指南）明确给出了关于块注释的规范原则：“块注释通常应用于其后跟随的部分（或全部）代码，并且与该代码保持相同的缩进层次。块注释的每一行都以 # 和一个空格开头。”

那么在日常开发中，究竟应当如何选择？可以通过以下决策流程来做出清晰判断：

五、全维度特性对照与总结

为了帮助开发者在实际编码中快速选择最合理的注释手段，下表全面梳理了多行 #、三引号临时注释与标准文档字符串的关键技术特性：

综上所述，三引号 ''' 或 """ 是 Python 中兼具灵活性与实用性的语法构造。正确掌握它的关键，是在临时编写多行注释时时刻注意缩进对其；在书写模块、类或函数的接口说明时规范使用 PEP 257 推荐的三双引号文档字符串；而在长期的工程级代码维护中，充分利用现代 IDE 的批量快捷键（如 Ctrl + / 或 Cmd + /）使用多行 # 号，保持代码严谨、清晰且易于维护。