Python为什么没有/* */多行注释符？三引号的本质解析

一、为什么 Python 不引入 /* */ 多行注释符？

很多习惯了 C、C++、Java 或 JavaScript 的开发者在接触 Python 时，都会产生同一个困惑：既然这些主流语言都同时支持单行注释与 /* ... */ 块级注释，为什么 Python 唯独缺少块级注释符？这并非疏忽，而是 Python 核心设计哲学与缩进语法机制共同决定的结果。

1. “做一件事只有一种显而易见的方式”

在著名的《Python 之禅》（The Zen of Python，PEP 20）中，有一条广为人知的核心格言：

There should be one-- and preferably only one --obvious way to do it.
（应该有一种——且最好只有一种——显而易见的方式来完成一件事。）

Python 继承自 ABC 语言与 Shell 脚本传统，选用了 # 作为注释符号。如果额外引入类似 /* ... */ 的块级注释，语法系统便同时存在两套并行的注释语法。在日常团队协作中，开发者便不得不面对一系列无谓的纠结：何时该用单行、何时该用块级、行内是否允许插入注释。只保留 # 一种注释机制，消除了开发者的选择成本，维护了语法的极简与纯粹。

2. 缩进语法（Off-side Rule）与块级闭合符的解析矛盾

更关键的底层障碍来自于 Python 独特的语法基石——依靠缩进界定代码块（越位规则，Off-side Rule）。在 C/Java 中，代码块完全由花括号 { ... } 显式圈定，空白符和换行不具备语法语义，词法分析器可以简单粗暴地将 /* 到 */ 之间的所有文本视为空白吞噬，完全不会影响花括号匹配。

但 Python 的词法分析器（Lexer/Tokenizer）肩负着特殊职责：它必须扫描每一行行首的空格与制表符，根据缩进层级的增减动态向语法分析器发射虚拟的 INDENT（缩进）和 DEDENT（反缩进）标记。假若引入跨行的 /* ... */，词法分析器就会陷入严重的歧义泥潭：

如上图所示，当跨行注释内部的缩进发生变化时，词法分析器很难在“跳过注释内容”与“准确判定代码块归属”之间保持平衡。而 # 单行注释只影响当前行从 # 到行尾的字符，换行符依然清晰可辨，行首缩进计算绝不受影响。这种优雅的线性解析是 Python 编译器保持健壮与快速的基石。

3. 现代编辑器的快捷键支持使块级符号成为冗余

在几十年前打孔机或纯文本编辑器时代，多行块注释能够减少程序员的手动键入量。但 Python 极具前瞻性地将这种多行操作交给开发工具完成：

• Windows / Linux：选中任意多行代码，按下 Ctrl + / 即可一键批量加上或去除 #。
• macOS：选中任意多行代码，按下 Cmd + / 即可批量切换。

当现代 IDE 能够以毫秒级完成多行 # 的生成与撤销时，在核心语法中专门引入 /* */ 的工程必要性便彻底消失了。

二、三引号的底层本质：它从来不是注释

既然官方没有 /* */，为什么网上许多教程都声称“Python 可以用三引号进行多行注释”？这种说法虽然在初学者中广为流传，但在语法机制上是不折不扣的认知偏差。三引号包裹的文本，本质上是多行字符串字面量（Multiline String Literal）。

1. 真正的注释 vs 三引号的编译差异

在 Python 的编译管线中，# 注释与三引号字符串在词法分析阶段就分道扬镳：

• # 单行注释：在词法分析（Lexical Analysis）阶段，扫描器将其标记为 COMMENT token，随后立即从标记流中丢弃。它不会进入抽象语法树（AST），编译器对其视而不见，生成字节码时为 0 字节。
• 三引号字符串（''' 或 """）：在词法分析阶段被识别为合法的 STRING token，随后完整送入语法分析器，构建为一个抽象语法树节点（在 Python 3.8+ 中统一为 ast.Constant 节点）。

2. 为什么三引号能够“假装”成注释运行？

既然三引号是字符串，为什么把它随意写在代码中间，程序运行却不会报错？这是因为在 Python 语法规则中，单独存在的字面量属于合法的“表达式语句”（Expression Statement）。

例如，我们在函数体内单独写一行数字或单引号字符串：

def demo():
    1024            # 合法的表达式语句
    "hello world"   # 合法的表达式语句
    return True

在编译为字节码时，Python 编译器内置的窥孔优化器（Peephole Optimizer）会进行死代码消除（Dead Code Elimination）：它检测到这个字符串字面量既没有赋值给任何变量，也没有传递给任何函数，更不会产生任何运行时副作用（Side-effect），因此会在字节码生成阶段将其安全剥离。这就是孤立三引号在表面上“看起来像注释”的底层机理。

三、三引号作为“假注释”的隐藏代价与踩坑场景

虽然未引用的三引号字符串在最终字节码中不占运行开销，但由于它本质上是一条完整的 Python 语句，必须全程接受词法与语法分析器的严格审查。如果将其当作注释滥用，将引发诸多棘手的隐蔽问题。

1. 缩进错误：必须严格服从代码块的缩进层级

真正的 # 注释可以放置在行内的任何列位置，即使写在最左侧第 0 列，也绝不会打乱函数内部的代码块结构。然而，三引号作为表达式语句，其首行缩进必须与当前上下文严格对齐。例如：

def calculate_tax():
    rate = 0.15
"""
临时注释掉扣除项逻辑
deduction = 5000
"""
    return rate

运行上述代码，解释器会立即抛出阻断性错误：

IndentationError: unindent does not match any outer indentation level

原因是词法扫描器在第 3 行遇到了缩进为 0 的三引号，判定函数作用域已结束；紧接着在第 7 行又遇到了 4 个空格缩进的 return，导致语法解析彻底崩溃。

2. 转义字符校验与语法警告（SyntaxWarning）

在 # 注释中，你可以随意书写任意特殊字符，甚至是非法的反斜杠。但三引号字符串在词法分析时会严格进行转义字符求值。在 Python 3.8+ 及特别是 Python 3.12+ 中，若被注释的代码段包含未转义的反斜杠（如正则表达式或 Windows 文件路径）：

def execute_job():
    """
    备用路径记录：
    backup_path = "D:\target\new_folder"
    pattern = "\d+\w+"
    """
    pass

编译阶段会立刻触发编译警告，并在后续 Python 版本中直接升级为语法错误（SyntaxError）：

SyntaxWarning: invalid escape sequence '\t'
SyntaxWarning: invalid escape sequence '\d'

3. 污染 __doc__ 属性并常驻内存

如果三引号恰好放置在模块顶部、类声明第一行或函数体第一行，Python 编译器不会将其丢弃，而是会将其作为文档字符串（Docstring）绑定到对象的 __doc__ 属性上，并存入代码对象的常量表（co_consts）中，常驻内存：

def get_active_users():
    """
    TODO: 临时注释掉上一版的 SQL 查询代码
    SELECT * FROM users WHERE status = 1 ORDER BY created_at DESC;
    ... (大段废弃的调试片段) ...
    """
    return []

print(get_active_users.__doc__)  # 原本应展示 API 文档，此时全部变成废弃垃圾代码

这不仅导致垃圾代码常驻内存，还会导致自动化文档工具（如 Sphinx、pydoc、Swagger 生成器）把废弃代码直接渲染进对外公开的 API 文档中。

四、正确的多行注释规范与实用指南

为了编写高质量、符合工业级标准的 Python 代码，我们需要彻底厘清 PEP 8 与 PEP 257 两个核心规范的分工边界。

1. PEP 8 关于多行注释的标准指引

官方代码风格指南 PEP 8 在“块注释（Block Comments）”小节中给出了极其明确且排他的指引：

• 块注释通常适用于跟随其后的一段或全部代码，并且应该与该代码缩进至相同级别。
• 块注释的每一行都必须以 # 和一个空格开头（除非注释内部存在缩进段落）。
• 块注释内部的段落之间，应该用只包含单个 # 的空行隔开。

标准的多行注释示例如下：

# 核心算法处理管线：
# 1. 对输入向量执行 L2 归一化，消除量纲影响；
# 2. 计算各样本与聚类中心的余弦相似度；
#
# 注意：当输入向量模长为零时，将自动填充默认基准值
# 以避免浮点数除以零引发 ZeroDivisionError 异常。
def normalize_and_score(vector):
    pass

2. PEP 257 关于文档字符串的标准指引

三引号唯一的正统舞台是 PEP 257（Docstring Conventions） 所定义的文档字符串。文档字符串专为模块、函数、类和方法撰写使用说明，供开发者阅读并由自动化工具提取：

def fetch_user_profile(user_id: int) -> dict:
    """根据用户唯一标识获取用户详细资料。

    参数:
        user_id: 用户的整型唯一标识符，必须为正整数。

    返回:
        包含用户昵称、注册时间和权限组的字典数据。

    抛出:
        ValueError: 当 user_id 小于等于 0 时抛出。
    """
    if user_id <= 0:
        raise ValueError("user_id 必须为正整数")
    return {"id": user_id, "name": "Alice"}

五、总结

回顾 Python 的语法设计历程，没有引入 /* */ 多行注释符并不是功能的缺失，而是对“极简哲学”与“缩进语法完整性”的坚守：

1. 语法设计的统一性：坚持“用一种显而易见的方式解决问题”，避免因冗余语法带来社区分裂与规范成本。
2. 词法解析的稳健性：避免块级闭合符穿透不同缩进层级引发的 INDENT/DEDENT 状态歧义。
3. 三引号的本质还原：三引号从底层到规范永远是字符串字面量。它之所以能作为临时废弃手段，是因为无副作用的独立表达式语句在优化期会被编译器丢弃，但它绝不能替代真正的注释。

在日常开发中，请养成使用 IDE 快捷键（Ctrl + / 或 Cmd + /）批量添加 # 进行多行注释的良好习惯，让三引号回归到其作为文档字符串（Docstring）与跨行文本的专属使命中。