Python单行注释与多行注释的语法区别

一、单行注释的语法机制与编译器行为

Python 单行注释以井号 # 开头，作用范围从 # 字符开始，直到当前物理行的换行符结束。单行注释既可以独立占据一整行（常用于解释后续代码块的逻辑），也可以放置在可执行代码行的末尾（行内注释）。

理解单行注释的关键在于词法分析阶段（Lexical Analysis）的处理方式。当 Python 解释器的词法扫描器（Tokenizer）解析源代码时，一旦遇到不在字符串字面量之内的 # 字符，便会立刻截断该行，将 # 及其后面的所有文本直接从字符流中剔除。

# 独立单行注释：初始化订单状态与重试计数器
def init_order(order_id: str):
    status = "PENDING"  # 行内注释：初始状态默认为待处理
    retry_count = 0     # 行内注释：当前重试计数
    return {"id": order_id, "status": status, "retry": retry_count}

因为在词法扫描时已被丢弃，单行注释在后续的语法分析阶段不会生成任何抽象语法树（AST）节点，更不会在字节码编译器（Bytecode Compiler）中生成对应的指令。编译生成的 .pyc 文件中完全不包含单行注释的内容，因而在程序运行时，单行注释对内存占用和执行效率的开销为严格的零。

二、“多行注释”的语法本质：连续井号 vs 三引号字符串

与其他主流语言（如 C/Java 中的 /* ... */）不同，Python 并没有专门设计成对的多行注释独立语法标记。在实际编写多行说明时，开发者通常接触到两种形式：

1. 连续多行 #（块注释，Block Comments）： 在每一行需要注释的文字开头均显式添加 #。这在语法上就是连续的单行注释，也是 Python 官方 PEP 8 编码规范唯一正式推荐的多行代码逻辑注释方案。
2. 三引号多行字符串（''' 或 """）： 利用成对的三单引号或三双引号包裹多行文字，且不将其赋值给任何变量。很多初学者常因其“不会产生输出”而将其直接视作多行注释。

然而，三引号文本在 Python 语法体系中的真实身份是多行字符串字面量（Multi-line String Literal）。虽然它没有赋值给变量，但在语法层面它是一个合法的表达式语句（Expression Statement）。词法扫描器会将其完整识别为 STRING Token 并保留其中的换行与空格；语法分析器会为其构建 AST 树中的 ast.Expr 和 ast.Constant 节点。

如图 1 所示，三引号字符串是否会被优化，取决于其所处的作用域位置：

• 位于模块、类或函数定义体首行：Python 解释器会将其专门捕获并绑定为对象的文档字符串，持久存入其 __doc__ 属性中，运行时常驻内存。
• 位于逻辑代码中间：虽然 CPython 的字节码优化器（Peephole Optimizer）在生成字节码时可能会丢弃这种无副作用的无引用常量表达式，但它依然必须完整通过词法与语法分析，且受到 Python 语言所有语法的严格制约。

三、关键语法区别深度剖析

正是由于“原生注释标记”与“字符串表达式”的本质差别，两者在实际编码中表现出多项重大的语法区别：

1. 代码块缩进的约束与报错区别（IndentationError）

单行注释由于在词法扫描阶段即被抹除，不会影响 Python 的 INDENT 与 DEDENT 块级缩进记号生成。即使某行 # 的缩进稍微不齐，解释器也不会报错。

相反，三引号字符串作为有效语句，必须无条件遵守当前代码块的缩进层级。如果在缩进代码块（如函数体、循环体、if 分支）内部使用三引号充当“多行注释”，其起始引号、内部换行以及结束引号均不能随意顶格或错位，否则解释器会在编译期直接抛出 IndentationError 致命语法错误。

2. 运行时内存驻留与文档反射机制（__doc__）

单行注释在运行时完全“蒸发”，没有任何内置机制能在程序执行期提取这些注释内容（除非外部调试器自行读取并解析 .py 源码文本）。

而三引号字符串若是放置在模块、类或函数定义的起始位置，会被 Python 解释器识别为文档字符串（Docstring），自动写入对应对象的 __doc__ 属性。开发者在运行时可以通过 help() 函数查看，自动化文档工具（如 Sphinx、pydoc）也能通过反射直接抽取。

def calculate_tax(income: float) -> float:
    """计算个人所得税应纳税额。
    
    参数:
        income: 税前月收入（元）
    返回:
        应纳税额度
    """
    # 扣除起征点 5000 元后按阶梯税率核算
    taxable = max(0.0, income - 5000.0)
    return taxable * 0.1

# 运行时验证反射能力
print(calculate_tax.__doc__)  # 输出三引号中的完整文档
# 而单行注释 "# 扣除起征点..." 在运行时无法通过 calculate_tax 对象获取

3. 字符转义机制与嵌套引号处理

在单行注释中，# 之后的一切字符都是纯文本，包含单引号、双引号、甚至反斜杠（\）都不需要进行任何转义处理。

然而在三引号字符串中，如果内容本身包含了相同的三引号闭合符（例如在 """...""" 内部嵌套出现 """），解释器会提前判定字符串结束，产生意外的语法解析错误；若文本中包含形如 \n、\t 或 Windows 路径 \U 等反斜杠序列，字符串求值时会触发转义处理，在 Python 3.12+ 中未经处理的无效转义还会触发 SyntaxWarning: invalid escape sequence。

四、常见缩进与作用域陷阱剖析

将三引号字符串当做多行注释随意使用时，极易踩入以下两个典型的结构性陷阱：

五、PEP 8 与 PEP 257 官方规范与工程实践最佳准则

为了杜绝上述歧义与隐患，Python 官方在两份权威规范中做出了极其明确的分工指引：

• PEP 8（Python 代码风格指南）： 明确规定块注释（Block Comments）应该由一条或多条以 # 开头且缩进对齐的单行注释构成。段落之间可以使用仅含单个 # 的空行进行分隔。对于单行行内注释，要求与前方代码保持至少 2 个空格距离，# 后保留 1 个空格。
• PEP 257（文档字符串规范）： 明确规定三双引号 """...""" 专属用于编写文档字符串（Docstring）。任何不属于公共接口文档的内部实现细节说明，均不应滥用三引号。

六、常见疑难问题排错指引（FAQ）

Q1: 为什么很多基础教程会把三引号称为“多行注释”？

在 Python 交互式命令行或脚本执行时，如果一个字符串字面量独立成行且未被赋值，它在执行时虽然被求值但没有任何可观测的外部副作用，也不会在控制台打印任何结果。这使得它在视觉和效果上非常接近其他编程语言的块注释，因此被早期教程作为一种非官方的“多行注释替代方案”广泛传播。但在深入学习 Python 编译机制和严谨的工程开发中，必须认清其字符串表达式的本质。

Q2: 使用三引号注释大段临时调试代码会有性能损耗吗？

在函数体内部，未被引用的字符串字面量通常会在 CPython 的字节码优化阶段被剥离，因而对运行速度的影响微乎其微。但是，它仍然会在每次解释器启动或重新编译模块时被词法扫描器完整解析并验证转义符号。更严重的隐患在于：如果被注释的代码中包含未闭合的单双引号、特殊反斜杠路径或不规则缩进，会导致整段脚本在编译阶段直接崩溃。因此，临时屏蔽多行代码请一律使用编辑器的 Ctrl + / 快捷键添加 #。

Q3: 单行注释的 # 能写在一行代码的中间吗？

不能。一旦词法扫描器遇到 #，该字符到该行末尾的所有字符均被视作注释。如果将 # 置于一行有效代码的前半部分，其右侧的所有正常逻辑都将随之失效，通常会立即导致 SyntaxError: invalid syntax 语法错误。