Python的三种注释写法:单行#、多行三引号与文档字符串

Luna
Luna
发布时间:2026-11-18 | 8人浏览过
原创

深入讲解Python中单行注释(#)、多行三引号字符串以及文档字符串(Docstring)的语法规则、底层运行机制、PEP 8规范及使用场景选型。

在Python日常编码中,开发者通常会接触到三种“用来辅助说明代码”的表达方式:单行井号(#)、多行三引号(''' 或 """)以及文档字符串(Docstring)。尽管它们经常被笼统地称为“注释”,但Python解释器对它们的解析机制、内存表现和适用场景有着本质区别。本文将直接梳理这三者的语法规则、底层运作方式以及在实际工程中的选型规范。

一、单行注释:官方正规注释语法 #

在Python语言规范中,严格意义上的注释标记只有一个,那就是井号 #。当Python解释器在词法分析阶段扫描到 # 时,会将该符号及其本行后续的所有字符直接识别为 COMMENT 标记,并在构建抽象语法树(AST)之前彻底丢弃。这意味着单行注释完全不会占用编译后的字节码体积,也不会在运行时产生任何性能损耗。

按照PEP 8官方代码风格指南,单行注释通常有两种摆放方式:独立行块注释与行尾行内注释。

1. 独立行注释

注释独占一行,置于所要解释的代码上方。# 后面必须跟一个半角空格,与下方代码保持同级缩进:

# 计算扣除基础税费后的净收益额
net_profit = gross_income - base_tax

2. 行尾注释(Inline Comments)

注释直接写在代码语句末尾。规范要求代码末尾与 # 之间至少保留两个空格,# 之后保留一个空格。行尾注释应当只在补充说明非常规逻辑或边界取值时使用,过度密集的行尾注释会显著干扰代码本身的阅读:

retry_count = 3  # 网络抖动时的最大重试次数

如果有多行内容需要解释,PEP 8推荐的做法不是依赖其他特殊符号,而是连续在每一行开头添加 #,构成整齐的块注释(Block Comments):

# 第一步:核验用户Token签名是否合法
# 第二步:从缓存读取权限列表,若未命中则回源数据库查询
# 第三步:校验用户是否具有当前路由的执行权限
permission_granted = verify_user_access(token, route)
Python的三种注释写法:单行#、多行三引号与文档字符串
图1:Python词法与语法分析阶段对不同注释与字符串的处理流向

二、多行三引号:未赋值字符串充当的“伪多行注释”

很多从C、Java等语言转入Python的开发者会寻找类似 /* ... */ 的原生块注释符号。Python语言本身并没有专门的多行块注释标记,但在实践中,许多人习惯使用成对的三引号(''' 或 """)将多行文字包裹起来,作为跨行注释使用。

这种写法的技术本质并不是真正的注释,而是一个未赋值给任何变量的字符串字面量(Unassigned String Literal)。在语法层面上,它是一个独立的表达式语句(Expression Statement)。在Python字节码编译阶段,由于该常量没有赋值给变量也没有参与后续运算,编译器(peephole optimizer)通常会将其直接忽略,因此在执行期同样不会产生明显的运行负担:

"""
以下代码用于排查连接池泄露问题:
通过模拟并发请求检查游标释放状态。
当前在生产环境下默认关闭。
"""
def debug_connection_pool():
    pass
注意缩进限制:由于三引号本质上是Python语法树中的语句,它必须严格遵循Python的缩进缩进规则。如果将三引号放在一个缩进块(例如 if 分支或函数体)内部,三引号的首行和每一行都不能打破当前的缩进级别,否则会直接触发 IndentationError。
def process_data(items):
    if len(items) > 0:
        # 正确:与当前代码块保持同样的4空格缩进
        """
        临时关闭数据预清洗流程
        items = clean(items)
        """
        save_to_db(items)

若将上述三引号顶格写在第0列,代码解析就会失败。因此,PEP 8并不推荐将三引号作为正式的多行注释方案,它的最佳适用场合是:本地开发调试时,临时大段注释掉测试代码或草稿记录。

Python的三种注释写法:单行#、多行三引号与文档字符串
图2:三种注释写法的语法特征、运行时表现与规范要求对比

三、文档字符串:一等公民的元数据 Docstring

文档字符串(Docstring)在形式上也使用三引号(或者单行双引号),但它的位置决定了它的特殊身份。当一个字符串字面量出现在模块、类、方法或函数定义的第一条有效语句时,Python解析器会给它赋予特殊的地位:不仅不会丢弃,还会将其编译并自动绑定到该对象的 __doc__ 内置属性中。

通过这种机制,文档字符串成为了Python对象的运行时元数据。开发者可以在交互式环境通过内置函数 help() 动态阅读说明,各类现代IDE(如VS Code、PyCharm)也能通过静态分析提取Docstring,在鼠标悬停时展示参数类型与调用方法;自动化文档工具(如Sphinx、MkDocs)更可以直接扫描代码并生成在线技术手册。

1. 标准函数Docstring示例

def calculate_discount(price: float, rate: float) -> float:
    """计算商品的折后实际价格。

    参数:
        price (float): 商品原价,必须为正数。
        rate (float): 折扣比例,范围在 0.0 到 1.0 之间。

    返回:
        float: 计算后的折后价格。

    异常:
        ValueError: 当原价或折扣比例不符合范围要求时抛出。
    """
    if price < 0 or not (0.0 <= rate <= 1.0):
        raise ValueError("参数数值超出合理范围")
    return price * rate

2. 运行时反射与交互式检查

当我们在代码外部调用该函数时,可以通过属性访问或 help() 实时提取这段说明:

# 方式一:直接打印底层绑定的 __doc__ 属性
print(calculate_discount.__doc__)

# 方式二:在终端交互式控制台调用内置帮助函数
help(calculate_discount)

PEP 257(Docstring Conventions)专门针对文档字符串制定了详尽的规范:单行Docstring应直接在闭合引号前结束,且首尾不留换行;多行Docstring应当在首行简明扼要概括函数功能,空出一行后再展开详细的参数说明和返回值清单。

Python的三种注释写法:单行#、多行三引号与文档字符串
图3:Docstring在函数对象中的存储属性以及与反射工具的交互结构

四、三大写法的选型依据与常见误区

理解了底层的运行逻辑之后,日常编写代码时的选择依据就变得非常清晰了:

注释写法 语法性质 首要目的 典型场景 违规或不当后果
单行 # 词法忽略标记 解释实现细节与“为什么这么写” 复杂算法片段、临时修正说明、非常规参数备忘 如果滥用于接口说明,工具链和 help() 均无法提取
多行三引号 未赋值字符串表达式 临时大段忽略代码(调试) 本地排查缺陷时快速屏蔽几十行调试逻辑 若内部缩进不规范,将导致代码直接报 IndentationError 崩溃
文档字符串 __doc__ 元数据 说明对象功能、参数规范与调用方式 模块头部说明、类与公有方法的API接口规范 若写在第二行或更后面,将退化为普通字符串,help() 失效

常见误区警示

  • 误区一:把三引号当成通用的“多行注释语法”。在Python中,如果需要在代码中间写多行说明,正规做法是多行连续使用 #。三引号在缩进块中具有严苛的对齐要求,且部分静态检查工具(如flake8、pylint)会将其警告为“无意义的字符串语句”。
  • 误区二:在函数签名与Docstring之间插入其他代码。如果函数第一行写了 count = 0,第二行再写 """说明""",Python解释器将不再把它识别为文档字符串,该字符串无法绑定到 __doc__。
  • 误区三:注释只复述代码在做什么。像 i = i + 1 # 让i自增1 这样的注释不仅毫无增量信息,还会增加维护成本。优质的注释应当回答“为什么需要自增”、“为什么这里上限是256”等设计决策层面的问题。
Python的三种注释写法:单行#、多行三引号与文档字符串
图4:根据注释目标与工程规范快速确定写法选型的决策路径

总结

回顾Python中的这三种写法:单行 # 是官方唯一的正规注释语法,贯穿于所有细部代码的意图传达;多行三引号是未绑定变量的字符串表达式,仅适合在开发调试时作为临时批量屏蔽代码的快捷工具;而文档字符串(Docstring)则是语言内置的一等文档元数据,专为模块、类和函数的公共API说明服务。在日常开发中,做到“接口用Docstring规范说明、细节用 # 讲透原因、避免把三引号带入生产代码”,就能写出既符合PEP 8规范又易于团队维护的高质量Python程序。

相关专题:

本站声明

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

Python 相关产品和应用

全部下载

专题列表