Python中的注释符号是什么：单行#与多行三引号用法

一、Python 注释符号的本质：为什么官方只有 # 号

初学者查阅 Python 语法手册时，经常会产生一个疑问：许多教程既提到了 #，又演示了成对的三引号，究竟哪一个才是官方规定的注释符号？

答案在 Python 官方词法分析规范（Python Language Reference: Lexical Analysis）中有明确界定：Python 语言中唯一的注释字符是井号（#）。当 Python 解释器的词法分析器（Lexer）读取源代码字符流时，一旦遇到不在字符串字面量内部的 # 字符，该字符及其后直至本行行末的所有内容都会被彻底忽略，完全不参与后续语法标记（Token）的生成，也不会进入抽象语法树（AST）。

单行注释在日常编写中主要有两种应用形式：独占一行的块注释（Block Comments）以及跟在代码语句后方的行尾注释（Inline Comments）。

# 这是标准的块注释：独占一行，解释后续逻辑
def calculate_discount(price, rate):
    # 校验折扣率是否处于合理区间 0 到 1 之间
    if not (0 < rate <= 1.0):
        raise ValueError("折扣率必须在 0 到 1 之间")
    
    final_price = price * rate  # 计算折后实付价格（行尾注释）
    return final_price

二、如何做决策：单行、多行与文档说明的选用流程

既然官方语法没有专门提供类似 C/Java 的 /* ... */ 原生多行注释标记，我们在日常开发中面对复杂的多行说明、模块架构描述或临时代码调试时，应该如何选择最恰当的表达手段？

根据 PEP 8 和 PEP 257 规范，开发者应遵循一条清晰的决断链路：若文字是为了供外部调用者与 IDE 查阅接口契约，必须使用三引号构建规范的 Docstring；若文字用于解释内部算法逻辑，推荐使用连续多行的 #；若仅是本地排查故障需要快速屏蔽整段已有代码，三引号或 IDE 快捷键是高效的临时手段。

1. 规范的多行注释方式：连续多行 # 号

Python 官方指南 PEP 8 明确推荐的多行长文本注释方式是在每一行开头都添加一个 # 符号。这种方式从语法层面具备最高安全性，完全不改变程序的抽象语法树结构，也不会带来意外的缩进陷阱。

# 数据预处理模块核心管道：
# 1. 过滤包含缺失关键字段（如 user_id、timestamp）的脏数据行；
# 2. 将 UTC 时间戳格式化为本地时区的 ISO-8601 标准字符串；
# 3. 对金额字段执行四舍五入并统一转换为以分为单位的整数。
def sanitize_records(raw_list):
    clean_list = []
    for item in raw_list:
        if item.get("user_id") is not None:
            clean_list.append(item)
    return clean_list

在现代代码编辑器（如 VSCode、PyCharm、Cursor）中，开发者只需选中多行代码并按下组合快捷键 Ctrl + /（macOS 下为 Cmd + /），编辑器就会自动在选中的每一行行首添加或移除 #，其实际操作效率甚至高于手动敲击成对的三引号。

三、深入底层：三引号多行字符串与 # 注释的运行机制

许多初学者会将包裹在三单引号 ''' 或三双引号 """ 之间的文字称为“多行注释”。在很多场景下这确实能起到不影响程序运行的效果，但深入解释器底层会发现，两者的运行原理存在根本差别。

三引号在 Python 中的正统语法身份是多行字符串字面量（Multi-line String Literals）。理解它的运行逻辑需要区分两个关键阶段：

• 词法分析与 AST 构建阶段：词法分析器不会丢弃三引号内容，而是将其完整解析为一个完整的 STRING 标记（Token），并在抽象语法树中实例化为一个常量表达式节点（ast.Constant）。
• 字节码生成阶段：如果该三引号字符串不是紧跟在模块、类或函数定义后的第一条有效语句，且没有通过等号赋值给任何变量，Python 编译器的代码优化器会识别出该表达式没有产生副作用（Side-effect free），进而在输出 .pyc 字节码时将其从执行指令流中剔除。

def demo_error():
    x = 10
# 错误写法：三引号顶格写，破坏了函数体4空格缩进
"""
临时屏蔽下面这行计算逻辑：
x += 20
"""
    return x
# 运行结果：IndentationError: unexpected indent / unindent

四、三引号的标准使命：文档字符串（Docstring）与 PEP 257 规范

如果说 # 注释是写给代码维护者看的“实现细节说明”，那么三引号的真正核心价值在于充当“文档字符串（Docstring）”，它是写给调用者看的“接口使用契约”。

当三单引号或三双引号紧跟在模块开头、类定义首行或函数定义首行时，Python 解释器会做特殊处理：它不仅不会丢弃该字符串，还会自动将其编译并绑定到对应对象的 __doc__ 特殊属性中。

Docstring 的规范书写范例

根据 PEP 257（Docstring Conventions）约定，所有的文档字符串统一建议使用三个双引号（"""），而不是三单引号（'''）。单行文档字符串可以写在同一行，而多行文档字符串推荐采用总结行、空行加详细说明的结构：

def fetch_user_profile(user_id: int, timeout: int = 5) -> dict:
    """根据用户唯一标识拉取详细用户资料.

    通过内部 RPC 接口拉取用户基本信息与授权状态。如果遇到网络抖动，
    将在超时时间内最多自动重试两次。

    :param user_id: 系统分配的唯一整型用户 ID
    :param timeout: 请求超时阈值，单位为秒，默认为 5 秒
    :return: 包含 nickname, email 与 roles 的字典对象
    :raise UserNotFoundError: 当指定 user_id 在数据库中不存在时抛出
    :raise TimeoutError: 当网络请求超出指定等待时间时抛出
    """
    # 内部实现代码
    result = {"user_id": user_id, "status": "active"}
    return result

当这样编写之后，其他开发者在 IDE 中鼠标悬停在该函数上时，IDE 就能自动弹出格式化的高亮提示；在交互式控制台中执行 help(fetch_user_profile) 或直接打印 fetch_user_profile.__doc__ 也能即时获取到详尽文档，甚至自动化工具（如 Sphinx、pydoc）可以直接提取这些内容生成整套 HTML API 文档网站。

五、综合总结：单行 # 与多行三引号全维度对比

为了在工程开发中避免混淆和用错场景，下表与图示全面总结了 Python 中井号注释与三引号文本的核心差异：

六、写好 Python 注释的工程建议

掌握了注释符号与书写方式后，在实际编码中还应遵循“代码自解释”的工程共识：

• 注释回答“Why”，代码回答“What”：不要写纯粹复述代码字面意思的废话注释（如 i += 1 # 变量i自增1），而应解释为什么采取这种特殊的实现方式、背后有哪些业务规则约束或绕过了哪些已知缺陷。
• 随代码同步更新：错误的、过时的注释比没有注释危害更大。在重构或调整业务逻辑时，必须第一时间修正关联的单行 # 与 Docstring。
• 调试完成及时清理：临时使用三引号屏蔽的代码块，在提交到版本控制仓库（Git）前应当予以删除或转换为正规注释，避免在代码库中遗留大量未绑定字符串常量。