Python中怎么写多行注释:连续#号与三重引号的具体用法

林舟
林舟
发布时间:2026-11-22 | 14人浏览过
原创

深入讲解Python中写多行注释的两种主要方式:连续#号与三重引号。分析两者的语法本质、PEP 8与PEP 257规范、文档字符串Docstring应用及常见缩进陷阱。

在编写 Python 代码时,清晰的注释能够显著提升程序的可读性和可维护性。Python 并没有像 C 或 Java 中 /* ... */ 这样专门的多行块注释专用标记。在实际开发中,开发者主要通过两种方式实现多行内容的注释与说明:一是连续使用单行注释符号 #,二是利用三重单引号或三重双引号(''' 或 """)。掌握这两种写法的语法机制、规范差异以及各自的适用边界,是写出规范 Python 代码的基础。

一、两种方式的本质区别与解释器解析机制

许多初学者会将连续 # 和三重引号混为一谈,甚至认为三重引号就是 Python 的多行注释语法。事实上,两者在 Python 解释器底层的处理逻辑有着根本区别:

  • 连续 # 号:这是 Python 语法规范(PEP 8)唯一官方认定的正规多行注释形式。在词法分析阶段,词法分析器(Lexer)一旦扫描到 #,便会将该符号直至该行行尾的所有字符全部忽略,不会生成抽象语法树(AST)节点,更不会被编译成任何字节码。
  • 三重引号(""" / '''):在语法层面,它本质上是一个多行字符串字面量(Multi-line String Literal)。当它紧跟在模块、类或函数定义之后时,Python 会将其绑定为文档字符串(Docstring)并存入对象的 __doc__ 属性;若它单独出现在普通代码块中且未赋值给变量,虽通常会被编译器优化丢弃,但它依然需要通过严格的语法和缩进检查。
Python中怎么写多行注释:连续#号与三重引号的具体用法
图 1:Python 解释器处理连续 # 号与三重引号的机制对比

二、连续 # 号的具体用法与规范

在 Python 官方代码风格指南 PEP 8 中明确指出:块注释(Block Comments)通常应用于其后跟着的部分或全部代码,并且缩进至与该代码相同的级别。块注释的每一行都以一个 # 和一个空格开头。

1. 编写规范示例

编写连续 # 号注释时,需要保持符号与正文间留有空格,段落之间空行也需保留 #,使整块注释在视觉上构成连续的整体:

def process_user_data(users):
    # 下方逻辑负责清洗外部传入的用户数据集。
    # 过滤掉未验证邮箱的用户,并重新计算活跃度分值。
    #
    # 注意:该步骤在数据量超过10万条时应考虑批量分页处理,
    # 避免一次性加载造成内存溢出。
    valid_users = []
    for user in users:
        if user.is_verified:
            valid_users.append(user)
    return valid_users

2. 编辑器快捷键批量操作

手动为每一行添加 # 较为耗时,现代代码编辑器(如 VS Code、PyCharm、Sublime Text)都内置了批量添加和解除注释的快捷键:

  • Windows / Linux: 选中目标多行代码,按下 Ctrl + /
  • macOS: 选中目标多行代码,按下 Cmd + /

该快捷键为切换开关:未注释行会自动加上 # ,已注释行再次触发则会批量移除。

Python中怎么写多行注释:连续#号与三重引号的具体用法
图 2:在编辑器中批量管理多行 # 号注释的操作步骤

三、三重引号的具体用法与注意事项

三重引号包括三个单引号 ''' 或三个双引号 """。在 Python 语法中,它们允许字符串跨越多行而无需使用换行转义字符 \n。

1. 正规场景:文档字符串(Docstring)

根据 PEP 257 规范,三重双引号(""")主要用于模块、函数、类以及方法的文档编写。这是 Python 语言内建的一级特性:

def calculate_discount(price: float, rate: float) -> float:
    """计算折后价格。

    参数:
        price: 原商品价格(必须大于等于0)
        rate: 折扣率,取值范围在 0.0 到 1.0 之间

    返回:
        折后结算价格
    """
    if price < 0:
        raise ValueError("价格不能为负数")
    return price * rate

文档字符串会被编译并保存在函数的 calculate_discount.__doc__ 属性中,可以在终端直接通过 help(calculate_discount) 查阅,也会被 Sphinx 等自动化文档工具及 IDE 的鼠标悬浮提示实时捕获。

Python中怎么写多行注释:连续#号与三重引号的具体用法
图 3:文档字符串(Docstring)与业务代码注释的分工与层级位置

2. 借用场景:临时屏蔽大段代码

在本地调试代码排查错误时,有时需要临时停用多行逻辑,许多开发者会习惯性使用三重引号将其包住:

def export_report():
    print("开始导出报表...")
    
    """
    # 临时禁用的测试代码块
    test_server = connect_test_cluster()
    test_server.sync_mock_data()
    """
    
    real_db_export()
注意三重引号做注释时的“缩进陷阱”:

由于三重引号本质是一个多行字符串表达式,它必须严格服从当前的缩进层级。如果在函数内部顶格书写三重引号,Python 解释器在编译期会直接抛出 IndentationError 语法错误!

# 错误示范:在函数内顶格写三重引号会直接中断执行
def run_worker():
    step1()
"""
这里如果顶格写三引号,会触发:
IndentationError: unexpected indent
"""
    step2()

四、连续 # 号与三重引号对比及选型建议

为了在工程实践中避免混淆,我们可以从底层机制、规范支持、语法限制等多个维度对照两者的特性:

比较维度 连续 # 号注释 三重引号(""" 或 ''')
语法本质 真正的纯代码注释(Comment) 多行字符串字面量(String Literal)
PEP 规范定位 PEP 8 推荐的代码块标准注释 PEP 257 推荐的模块/类/函数 Docstring
缩进要求 无语法级强约束(行内任意缩进) 严格受限于当前代码块的作用域缩进
运行时可访问性 不可访问(已被编译阶段彻底丢弃) Docstring 可通过 __doc__ 访问读取
内部嵌套敏感性 不敏感,行内可写任意字符 若被注释代码内含有同名三引号会导致提前闭合
推荐使用场景 函数内部逻辑解释、算法解析、长期维护的代码说明 模块/函数接口文档说明;极其短暂的本地粗略调试
Python中怎么写多行注释:连续#号与三重引号的具体用法
图 4:连续 # 号与三重引号在项目中的选型决策图

五、总结

在 Python 中编写多行注释时,结论非常明确:对代码实现细节和业务逻辑进行多行解释,请始终使用连续的 # 号。配合现代编辑器的快捷键(Ctrl + / 或 Cmd + /),不仅效率极高,而且完全杜绝了缩进错误和解析隐患。三重引号则专注于充当模块、类与函数的文档字符串(Docstring),用来描述接口用途、参数与返回值。分清两者的分工与边界,能够使你的 Python 代码既优雅稳健,又符合社区标准规范。

相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表