Python没有专门的多行注释？详解三引号实现多行注释的原理

向北走

发布时间：2026-10-25| 4人浏览过

原创

在绝大多数编程语言中，单行注释与多行注释往往有各自独立的语法标记。例如 C 语言与 Java 中的 // 和 /* ... */，HTML 中的 。然而，初学 Python 的开发者在查阅官方语法规范时常常会感到困惑：Python 官方语法中严格定义的注释符号只有井号（#）。那么，在日常开发和各类教程中广为流传的三引号（''' 或 """）多行注释，究竟是怎么一回事？它为什么能够起到类似注释的作用，背后又隐藏着怎样的语法与编译原理？

一、语言设计的既成事实：Python 确实没有多行注释语法

从 Python 官方语言规范（Python Language Reference）与 PEP 8 编码规范来看，Python 在语法层面仅提供了一种注释机制，即以井号 # 开头直到行尾的字符序列。无论注释只有几个字还是需要连续解释几十行，官方规范推崇的标准做法都是在每一行开头添加 #。

既然官方没有专门设计类似 /* ... */ 的闭合式注释语法，为何大家可以用成对的三引号包裹大段文字？答案在于：三引号从来都不是注释符号，它在 Python 词法中是多行字符串字面量（String Literal）。只是在满足特定条件时，Python 解释器会将未赋值的字符串字面量当作无操作语句（No-op）处理，从而在运行效果上“等同于注释”。

图 1：Python 词法注释与未绑定字符串模拟注释的底层差异

二、三引号“充当注释”的核心机制：孤立表达式语句

要理解三引号为何能当作注释，首先需要理解 Python 的表达式语句（Expression Statement）。

在 Python 中，单独写一行字面量或表达式是完全符合语法规则的。例如在脚本中单独写：

100 + 200
"hello world"
[1, 2, 3]

上述语句没有将计算结果赋值给任何变量，也没有调用输出函数打印。Python 解释器在语法解析时，将它们统一当成合法的表达式语句执行。由于表达式计算后没有产生任何后续关联，计算结果便会被立即丢弃，对程序的外部状态不产生任何副作用。

同理，当使用成对的三引号包裹一段包含换行符的长文本时，Python 语法解析器将其解析为一个跨行的字符串字面量常量。如果这个字符串常量没有被赋值给变量（如 text = """..."""），也没有作为实参传入函数（如 print("""...""")），它就是一个孤立的字符串字面量表达式。

关键结论：三引号之所以“能用作注释”，并不是因为解释器认识它是注释，而是因为它是一个合法、求值后立即被丢弃、不产生任何副作用的 Python 字符串对象。

三、编译器做了什么？通过字节码探究运行期表现

既然三引号是一个合法的字符串对象，那它在程序运行时会不会额外消耗内存，或者降低程序的执行速度？我们可以利用 Python 内置的 dis 模块反编译字节码，观察解释器对真实注释与三引号字符串的具体处理方式。

import dis

def example_hash_comment():
    # 这是标准的单行注释
    # 无论写多少行，编译器都不会为它生成任何指令
    x = 10
    return x

def example_triple_quote():
    x = 10
    """
    这里是一段三引号文字
    写在赋值语句之后，它不是函数开头的Docstring
    """
    return x

print("--- 单行注释函数的字节码 ---")
dis.dis(example_hash_comment)

print("\n--- 三引号孤立字符串函数的字节码 ---")
dis.dis(example_triple_quote)

运行上述分析代码，得到的字节码输出如下：

--- 单行注释函数的字节码 ---
  7           0 LOAD_CONST               1 (10)
              2 STORE_FAST               0 (x)

  8           4 LOAD_FAST                0 (x)
              6 RETURN_VALUE

--- 三引号孤立字符串函数的字节码 ---
 11           0 LOAD_CONST               1 (10)
              2 STORE_FAST               0 (x)

 17           4 LOAD_FAST                0 (x)
              6 RETURN_VALUE

对比两者的反编译结果可以发现：在现代 Python（Python 3.7+）中，由于 AST 优化器在将语法树转为字节码阶段实施了死代码消除（Dead Code Elimination），函数体内部未赋值、未引用的普通孤立字符串字面量，根本不会生成加载常量（LOAD_CONST）或弹出栈顶（POP_TOP）的字节码指令。在最终生成的 .pyc 二进制缓存中，两者的执行指令完全一致。

图 2：三引号字符串在解释器编译与优化阶段的分流处理逻辑

四、三引号充当注释容易踩中的三大“暗坑”

尽管从运行结果上看，未绑定的三引号字符串能够被解释器优化掉，但正因为它本质上是语法语句而非真正的词法注释，在日常使用中极容易引发以下三类常见问题：

1. 致命的缩进陷阱（IndentationError）

真正的 # 注释是词法层面的，只要行首写了 #，整行内容在分词阶段就被跳过，不会对语法缩进块造成任何破坏。但三引号字符串是语句，必须遵守 Python 的缩进语法。如果在一个受缩进约束的代码块中，随手写了顶格的三引号多行字符串，程序将直接崩溃：

def calculate_tax(income):
    base = 5000
"""
【错误示范】
这里顶格写了三引号注释，破坏了函数内部的代码块缩进级别。
Python 直接抛出 IndentationError: unexpected unindent
"""
    return (income - base) * 0.2

2. 误伤 Docstring 导致文档被覆盖

根据 PEP 257 规范，如果一个多行字符串恰好位于模块、类定义或函数定义体的第一条语句，Python 会自动将其识别为该对象的文档字符串（Docstring），并将其直接赋值给对象的 __doc__ 属性。这会导致两点后果：首先，这段内容不会被优化掉，而是始终常驻内存；其次，它会覆盖原有的帮助文档，干扰 help() 函数以及 Sphinx 等自动化文档工具的输出。

def process_data(data):
    """
    开发者原本只想临时在这里写一段草稿备注：
    TODO: 待优化算法
    """
    return data * 2

print(process_data.__doc__)
# 输出即为上述草稿内容，原本应有的接口文档被误设！

3. 转义字符与语法封闭性检查

在 # 后面可以书写任何非法字符、未闭合的单双引号或反斜杠；但在三引号字符串中，Python 解析器依旧会按照字符串语法规则进行合法性检查。如果在三引号内部末尾出现反斜杠 \，或者嵌套了未转义的三引号，将直接引发致命的 SyntaxError: EOL while scanning string literal。

图 3：使用三引号替代真实注释时容易引发的异常场景

五、最佳实践：在 Python 中如何规范书写多行说明

了解了三引号在语法和执行机制上的本质之后，在工程实践中应当如何进行技术选型？Python 社区与官方文档给出了极其明确的准则：

业务逻辑说明与大段代码注释：首选连续的 #。现代主流代码编辑器与集成开发环境（如 VS Code、PyCharm、Sublime Text）均提供了快捷键（Windows/Linux 下为 Ctrl + /，macOS 下为 Cmd + /），可以单键对选中的任意多行代码批量添加或解除 #。这种方式绝对安全，既不会产生缩进异常，也不会造成任何潜在的语义混淆。
模块、类与函数的对外接口说明：必须使用三引号规范的 Docstring。这是三引号最正统、最推荐的用途。在定义体首行使用三对双引号 """ 撰写功能说明、参数列表与返回值规范。
排查临时调试：慎用三引号大面积包裹代码。如果要临时禁用某一段包含各种字符串或混合缩进的代码，尽量使用编辑器的多行 # 注释功能，避免被包裹代码内部的引号与三引号发生语法闭合冲突。

图 4：Python 多行说明与代码注释规范化选型路径

六、总结

归结起来，Python “没有专门的多行注释”是一个明确的设计事实。所谓用三引号实现多行注释，是借助了未被引用的多行字符串字面量在语法上属于合法表达式语句、求值后立即被释放的语言特性。

虽然现代 Python 编译器在绝大多数情况下会通过 AST 优化消除无用字面量的字节码开销，使得三引号在日常调试草稿中显得很方便，但它依旧受到严格的缩进规则、文档字符串绑定机制与转义语法约束。在严谨的生产级项目与正式代码维护中，遵循 PEP 8 规范、依靠批量 # 来撰写多行内部逻辑注释，依然是最稳健、最地道的 Python 编程习惯。