Python多行注释怎么写：#号堆叠与三引号的用法对比

一、两种多行注释写法的语法形式与基本操作

Python代码中的注释用于向阅读代码的人解释逻辑意图、算法边界或特殊考量。针对跨越多行的注释需求，常见实现方式如下：

1. 连续使用 # 号堆叠（官方标准块注释）

这是Python官方推荐的标准多行注释编写方式。每一行注释文本均以井号 # 开头，后接一个半角空格，并与下文关联的代码块保持相同缩进。

# 校验用户输入的数据载荷格式是否完整
# 若缺少关键认证字段或时间戳超出有效期
# 则直接拦截请求并记录审计日志
def validate_request_payload(payload):
    if "token" not in payload:
        return False
    return True

在主流开发工具（如VS Code、PyCharm、Sublime Text）中，编写这种多行注释非常高效：只需用鼠标或键盘光标选中需要注释的多行代码，按下快捷键 Ctrl + /（macOS系统为 Cmd + /），即可一键批量加上或去除每行开头的 #。

2. 使用未赋值的三引号多行字符串（字面量占位）

Python允许使用成对的三单引号 ''' 或三双引号 """ 定义跨行字符串。当一个多行字符串没有被赋值给任何变量，也没有作为函数的返回值时，它在语法上是一个独立的表达式语句，常被部分开发者借用作为临时多行注释：

def process_order(order_id):
    """
    以下为历史计算逻辑的临时说明：
    早期版本在此处计算运费抵扣，
    新版接口已将运费计算迁移至结算服务中心。
    """
    execute_settlement(order_id)

二、解释器底层机制：真正注释与字符串对象的编译差异

理解两种写法的本质差异，关键在于观察Python解释器在编译代码时的处理路径。

1. 词法分析（Tokenizing）阶段的丢弃与保留

当Python读取源码时，首先由词法分析器（Tokenizer）将文本切分为一系列Token标记：

• 针对 # 开头的注释：词法分析器将其识别为 COMMENT 标记。在进入语法分析并构建抽象语法树（AST）之前，所有的 COMMENT 标记会被解释器彻底剥离丢弃。后续的语法解析器与代码生成器完全接触不到注释文本。
• 针对三引号：词法分析器会将其识别为合法的 STRING 标记。它不是注释，而是一个具体的数据字面量，会顺利进入语法分析器，并构建为一个表达式语句节点（Expr(value=Constant(value='...'))）。

2. 字节码编译与内存表现

由于三引号在语法树中是真实的表达式，解释器在生成字节码时会根据其所处位置进行不同处理：

• 如果位于模块、类或函数的首行：它会被解释器赋予特殊语义，绑定为该对象的 __doc__ 属性（文档字符串），常驻内存，供内置函数 help() 或自动化文档工具读取。
• 如果位于逻辑代码中间：虽然CPython编译器的优化器会在生成最终字节码时尝试消除没有副作用的纯常量表达式，但在未开启优化或复杂作用域中，它仍可能会被分配常量空间，占用底层代码对象的常量表（co_consts）。

相比之下，连续 # 号注释在编译后完全不留痕迹，生成的字节码数量为绝对的零，不消耗任何运行时内存资源。

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

Python社区有着严格的编码风格指南，官方在两份核心增强提案（PEP）中明确划分了块注释与文档字符串的界限。

1. PEP 8 关于块注释（Block Comments）的明确定义

PEP 8 明确指出：块注释通常适用于其后跟随的部分或全部代码，并与该代码保持相同的缩进层次。块注释的每一行都必须以 # 和一个空格开头（除非注释内部存在用于排版的空行，空行也应包含单个 #）。PEP 8从始至终未将三引号列为常规逻辑注释的推荐方案。

2. PEP 257 关于文档字符串（Docstring）的约定

三引号在Python中的正统地位由 PEP 257 规范界定，专门用于撰写文档字符串。文档字符串的适用范围仅限于：模块开头、类定义体首行、函数或方法定义体首行。它的核心职能是向外部调用者阐明接口协议、参数含义、返回值及可能抛出的异常，属于对外的“接口说明书”。

四、场景选型与日常编码最佳实践

结合语法规则与工程协作要求，日常开发中推荐按以下场景进行明确选型：

1. 业务逻辑与算法说明：统一使用连续 # 号

当需要在函数内部解释一段复杂的数学推导、正则表达式含义、跨服务调用逻辑或特殊兼容性补丁时，一律使用 # 逐行堆叠。这能保证代码在各种静态检查工具（如Flake8、Pylint、Black）中无警告通过，且不会对运行时产生任何潜在干扰。

2. 接口文档与API定义：严格使用三引号 Docstring

为模块、类、公共方法提供说明时，必须使用三双引号 """。规范的Docstring不仅方便团队成员在IDE中悬浮光标查看参数提示，还能被Sphinx等文档工具自动化生成在线文档系统。

3. 临时屏蔽多行代码排查问题：优先使用快捷键 # 注释

在排查Bug或本地联调时，常需要暂时注释掉一大段现存代码。虽然三引号可以快速包裹，但若被屏蔽的代码段内部本身就包含三引号字符串或反斜杠转义字符，极易引发字符串非预期闭合，导致难以排查的语法错误。使用编辑器的 Ctrl + / 快捷键直接给选区加 #，是最稳妥、最干净的做法。

五、总结

回答“Python多行注释怎么写”这一核心问题：在Python中编写常规的多行代码注释，唯一符合PEP 8官方规范的方式是使用连续的 # 号逐行堆叠。利用现代IDE提供的快捷键，这种写法无论在输入速度还是排版整洁度上均具明显优势。

三引号字符串（"""）的职责应严格限制在模块、类和函数的文档字符串（Docstring）领域。理清注释（给开发者看的内部实现说明）与文档字符串（给调用者看的API规范）的界限，不仅能避免因缩进与意外闭合导致的语法陷阱，也是编写高质量、符合Pythonic设计哲学代码的基础要求。