Python的三种注释写法:单行#、多行三引号与文档字符串
深入讲解Python中单行注释(#)、多行三引号字符串以及文档字符串(Docstring)的语法规则、底层运行机制、PEP 8规范及使用场景选型。
#)、多行三引号(''' 或 """)以及文档字符串(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)
二、多行三引号:未赋值字符串充当的“伪多行注释”
很多从C、Java等语言转入Python的开发者会寻找类似 /* ... */ 的原生块注释符号。Python语言本身并没有专门的多行块注释标记,但在实践中,许多人习惯使用成对的三引号(''' 或 """)将多行文字包裹起来,作为跨行注释使用。
这种写法的技术本质并不是真正的注释,而是一个未赋值给任何变量的字符串字面量(Unassigned String Literal)。在语法层面上,它是一个独立的表达式语句(Expression Statement)。在Python字节码编译阶段,由于该常量没有赋值给变量也没有参与后续运算,编译器(peephole optimizer)通常会将其直接忽略,因此在执行期同样不会产生明显的运行负担:
"""
以下代码用于排查连接池泄露问题:
通过模拟并发请求检查游标释放状态。
当前在生产环境下默认关闭。
"""
def debug_connection_pool():
pass
if 分支或函数体)内部,三引号的首行和每一行都不能打破当前的缩进级别,否则会直接触发 IndentationError。
def process_data(items):
if len(items) > 0:
# 正确:与当前代码块保持同样的4空格缩进
"""
临时关闭数据预清洗流程
items = clean(items)
"""
save_to_db(items)
若将上述三引号顶格写在第0列,代码解析就会失败。因此,PEP 8并不推荐将三引号作为正式的多行注释方案,它的最佳适用场合是:本地开发调试时,临时大段注释掉测试代码或草稿记录。
三、文档字符串:一等公民的元数据 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应当在首行简明扼要概括函数功能,空出一行后再展开详细的参数说明和返回值清单。
四、三大写法的选型依据与常见误区
理解了底层的运行逻辑之后,日常编写代码时的选择依据就变得非常清晰了:
| 注释写法 | 语法性质 | 首要目的 | 典型场景 | 违规或不当后果 |
|---|---|---|---|---|
| 单行 # | 词法忽略标记 | 解释实现细节与“为什么这么写” | 复杂算法片段、临时修正说明、非常规参数备忘 | 如果滥用于接口说明,工具链和 help() 均无法提取 |
| 多行三引号 | 未赋值字符串表达式 | 临时大段忽略代码(调试) | 本地排查缺陷时快速屏蔽几十行调试逻辑 | 若内部缩进不规范,将导致代码直接报 IndentationError 崩溃 |
| 文档字符串 | __doc__ 元数据 |
说明对象功能、参数规范与调用方式 | 模块头部说明、类与公有方法的API接口规范 | 若写在第二行或更后面,将退化为普通字符串,help() 失效 |
常见误区警示
- 误区一:把三引号当成通用的“多行注释语法”。在Python中,如果需要在代码中间写多行说明,正规做法是多行连续使用
#。三引号在缩进块中具有严苛的对齐要求,且部分静态检查工具(如flake8、pylint)会将其警告为“无意义的字符串语句”。 - 误区二:在函数签名与Docstring之间插入其他代码。如果函数第一行写了
count = 0,第二行再写"""说明""",Python解释器将不再把它识别为文档字符串,该字符串无法绑定到__doc__。 - 误区三:注释只复述代码在做什么。像
i = i + 1 # 让i自增1这样的注释不仅毫无增量信息,还会增加维护成本。优质的注释应当回答“为什么需要自增”、“为什么这里上限是256”等设计决策层面的问题。
总结
回顾Python中的这三种写法:单行 # 是官方唯一的正规注释语法,贯穿于所有细部代码的意图传达;多行三引号是未绑定变量的字符串表达式,仅适合在开发调试时作为临时批量屏蔽代码的快捷工具;而文档字符串(Docstring)则是语言内置的一等文档元数据,专为模块、类和函数的公共API说明服务。在日常开发中,做到“接口用Docstring规范说明、细节用 # 讲透原因、避免把三引号带入生产代码”,就能写出既符合PEP 8规范又易于团队维护的高质量Python程序。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













