Python多行注释语法：三引号与#号的区别及使用规范

从 Python 语法规则的严格定义来看，Python 语言中真正的注释语法只有井号（#）一种。初学者常用来临时充当多行注释的三引号（''' 或 """），在语言规范中其实是“多行字符串字面量（Multi-line String Literals）”。尽管未被赋值的独立字符串常常被当成注释使用，但两者在编译解析、抽象语法树生成、缩进约束以及规范归属上存在根本差异。本文将详尽拆解底层的运作机制，并基于 PEP 8 与 PEP 257 规范明确多行注释的正确书写标准。

一、本质区别：注释与未赋值字符串字面量

理解二者差异的核心在于：Python 解释器在编译代码时，对待 # 与三引号的方式完全不同。

1. 井号（#）在词法分析阶段即被剔除
当 Python 解释器读取源码并进行词法分析（Tokenizing）时，遇到 # 便会直接忽略该字符直至行尾的所有内容。这些注释内容甚至不会进入抽象语法树（AST），更不会生成任何字节码指令。对于运行时的 Python 虚拟机（PVM）而言，注释在语义分析之前就已经彻底消失了。

2. 三引号本质是合法的表达式语句
无论三引号包裹的内容是否被变量接收，在语法解析器眼中，它都是一个完整的常量表达式。如果在函数体或模块首行，它会被作为文档字符串（Docstring）存入对应的 __doc__ 属性；如果出现在普通逻辑代码中间，它在 AST 阶段仍会作为一个独立的 Expr(value=Constant(...)) 节点存在，仅在生成字节码的优化阶段才可能被剔除。

import dis

def example_hash():
    # 这里是纯注释
    # 解释器在词法分析阶段直接忽略
    x = 10
    return x

def example_triple():
    """这是函数体内的独立三引号字符串"""
    x = 10
    return x

print("--- example_hash 字节码 ---")
dis.dis(example_hash)

print("\n--- example_triple 字节码 ---")
dis.dis(example_triple)

通过 dis 模块反编译可以观察到，example_hash 的常量表中只有 None 和 10；而在 example_triple 中，三引号内容被明确保留在函数的文档属性 __doc__ 中。若在普通循环或分支中随意写独立三引号字符串，虽然现代 CPython 优化器会去除无副作用的常量加载指令，但它依然需要经历完整的语法解析流程。

二、技术陷阱：滥用三引号的潜在风险

正因为三引号是一个表达式语句而非注释，在很多场景下将其作为多行注释使用，会引发难以察觉或不可预期的语法错误。

1. 严格的缩进约束（IndentationError）

作为合法的 Python 语句，未赋值的三引号字符串必须与所在逻辑代码块的缩进保持严格一致。在顶层使用时或许不易察觉，但一旦置于 if、for、def 或 class 等代码块内部，只要三引号未对齐缩进，或者内部行的回车对齐不合规，就会直接引发 IndentationError 导致程序崩溃。

相反，井号（#）行即便置于代码块内，无论在其后放置多少空格，或者缩进对齐稍有偏差，解释器都不会将其视为语法错误。

def calculate_discount(price):
    if price > 100:
        # 正确：#号跟随逻辑块缩进，或即使缩进不严谨也不会破坏AST
        # 此处进行高阶折扣核算
        discount = 0.8
"""
错误示范：若三引号顶格书写或缩进不匹配当前分支层次
在部分场景下会破坏代码块结构或触发 IndentationError: unexpected indent
"""
        return price * discount
    return price

2. 内部引号闭合冲突（SyntaxError）

当开发者想要用三引号“临时屏蔽”一大段已有代码时，如果被屏蔽的代码中已经包含了相同类型的单引号、双引号或另一个三引号字符串（例如多行文本拼接或内置函数说明），会导致最外层的三引号提前闭合。此时，剩余的下半段代码会变成非法语法，直接报 SyntaxError: invalid syntax。

三、PEP 8 与 PEP 257 规范：官方如何界定注释与文档

为了保持 Python 生态系统代码风格的一致性，Python 官方通过专门的增强提案明确了二者的职责边界：

• PEP 8（Style Guide for Python Code）：明确规定代码块注释（Block Comments）应该由一个或多个段落组成。段落中的每一行都应当以 # 和一个空格开头。PEP 8 从未建议使用三引号作为普通代码段的多行注释。
• PEP 257（Docstring Conventions）：专门规范了“文档字符串（Docstring）”。文档字符串必须由三双引号 """ 包裹，且仅用于模块（Module）、类（Class）、函数（Function）及方法（Method）的第一条逻辑语句。其核心职责是为调用者解释“接口做什么、输入输出是什么”，并支持通过 help() 函数以及 Sphinx 等文档生成器读取。

"""数据预处理与特征工程模块 (PEP 257 模块级文档字符串)

提供针对时序传感器数据的去噪、归一化及缺失值填充功能。
"""

class SensorProcessor:
    """传感器数据清洗类 (PEP 257 类文档字符串)

    属性:
        sampling_rate: 采样频率(Hz)
    """

    def __init__(self, sampling_rate: int = 100):
        self.sampling_rate = sampling_rate

    def denoise_signals(self, raw_data: list) -> list:
        """对输入的原始波形信号执行移动平均去噪 (PEP 257 方法文档字符串)

        参数:
            raw_data: 浮点数列表构成的原始时序序列
        返回:
            去噪后的同长度浮点数序列
        """
        # PEP 8 规范块注释：解释内部特定阈值的选择原因
        # 由于硬件采样噪声在 50Hz 工频附近存在波动，
        # 此处采用固定窗口大小为 5 的加权滑动平均算法。
        window_size = 5
        filtered_result = []
        
        for i in range(len(raw_data)):
            # 行内注释：至少与代码间隔两个空格，以 # 加一个空格开头
            start_idx = max(0, i - window_size + 1)  # 边界防溢出裁剪
            sub_window = raw_data[start_idx : i + 1]
            filtered_result.append(sum(sub_window) / len(sub_window))
            
        return filtered_result

四、现代 IDE 多行注释操作技巧与生产规范

既然 PEP 8 推荐在多行注释中逐行使用 #，许多开发者会担心“手动每行加井号效率过低”。事实上，主流代码编辑器和集成开发环境（IDE）均内置了一键切换多行注释的功能。

1. 常用编辑器多行注释快捷键

在任何现代编辑器中，选中多行代码后按下快捷键，编辑器会自动在所选每行的开头插入 # ，再次按下则自动解开注释：

• VS Code / Cursor： Windows/Linux 下按 Ctrl + /，macOS 下按 Cmd + /。
• PyCharm / IntelliJ IDEA： Windows/Linux 下按 Ctrl + /，macOS 下按 Cmd + /。
• Sublime Text / Atom： 同样默认为 Ctrl + / 或 Cmd + /。
• 区块注释快捷键： 若需在特定支持的工具中生成整块包裹，VS Code 对应的是 Shift + Alt + A。但在 Python 模式下，官方推荐的插件仍优先将其转为连续的 #。

2. 规范速查对比总结

为了帮助大家在日常编码中快速决断，下表总结了三引号与 # 的全方位对比：

五、总结

在 Python 开发实践中，井号（#）是语法上唯一的注释方式，也是 PEP 8 推荐的多行注释标准做法；而三引号（''' 或 """）则是字符串字面量，其核心用途是编写符合 PEP 257 规范的模块、类与函数文档字符串（Docstrings）。

理清二者的本质区别，不仅能规避缩进断裂和引号冲突等隐蔽错误，更能让代码结构清晰、规范严谨，便于后续的维护与团队协作。