Python注释用什么符号?单行#与多行三引号写法详解
详细解答Python注释使用什么符号,系统讲解单行注释井号(#)的基础语法与PEP 8规范、多行三引号('''与""")的本质与区别,以及文档字符串Docstring与常规多行注释的选择建议与常见避坑指南。
#),它用于单行注释以及由多个单行组成的连续多行注释。对于多行文本说明,Python开发者常使用三个单引号(''')或三个双引号(""")包围多行内容;但从语言机制上讲,三引号属于未赋值的多行字符串字面量(Docstring / 字符串常量),而非语法意义上的注释关键字。本文将具体拆解单行与多行的规范写法、底层原理与避坑要点。
一、单行注释符号:井号(#)的基础语法与规范
在Python中,凡是在行内以 # 开头的位置,其后一直到该行行尾的所有字符,都会被Python解析器直接忽略,不参与任何代码执行与字节码编译。
1. 独立行单行注释
独立行注释通常放置在需要解释的代码上方,用于对后续代码块的功能、实现逻辑或设计意图进行说明:
# 计算订单总金额,并应用当前会员等级折扣
discount = 0.85
final_price = original_price * discount
2. 行尾注释(Inline Comments)
行尾注释位于代码语句的同一行尾部,适合对单个变量、特殊参数或边界值进行快速标注。根据Python官方PEP 8代码风格规范,编写行尾注释时有两项关键排版要求:
- 行尾空两格:代码语句与
#之间,应至少保留两个空格; - 井号后空一格:
#符号与后面的中文或英文文字之间,必须空出一个空格。
timeout = 30 # 网络请求超时时间(单位:秒)
retry_count = 3 # 失败后最大重试次数
二、多行注释的两种写法:连续井号与多行三引号
当注释内容较多、需要跨越数行进行技术推导或业务解释时,Python开发者通常有以下两种书写方式:
写法一:连续多个井号(PEP 8 推荐规范)
这是Python官方推荐的常规多行注释写法。每行开头均放置一个 # 符号:
# 第一步:读取本地CSV交易记录
# 第二步:过滤金额小于0的异常数据
# 第三步:按用户ID聚合计算总金额
filtered_data = [row for row in raw_records if row['amount'] > 0]
连续井号的优势在于安全与纯粹:它在编译期被彻底剥离,绝不会产生缩进异常,也不会占用任何内存空间。
写法二:成对三引号(''' 或 """)
使用连续三个单引号 ''' 或三个双引号 """ 将多行说明文字包裹起来:
"""
注意:
以下数据结构仅支持 UTF-8 编码文本;
如果遇到未知字节流,解析器将抛出 DecodeError。
"""
parse_stream(stream_data)
虽然Python允许这样写并且这段文字在未赋值时不会产生可见影响,但严格来说,三引号创建的是一个多行字符串对象(String Literal),它与 # 在底层行为上有着本质区别。
三、深度解析:三引号是“真注释”还是“文档字符串”(Docstring)?
很多初学者容易将三引号直接等同于“多行注释”,这在日常理解上没有大碍,但在Python语言设计中,三引号的首要职责是文档字符串(Docstring)。
1. 文档字符串的特殊机制与 __doc__ 属性
当三引号紧跟在模块最上方、函数定义声明首行、类定义首行时,Python解析器会把这个字符串对象赋予该对象的 __doc__ 内置属性:
def calculate_tax(amount: float, rate: float = 0.05) -> float:
"""计算商品销售税额。
参数:
amount: 基础消费金额(浮点数)
rate: 税率,默认为 5% (0.05)
返回:
计算出的应缴税额
"""
return amount * rate
# 运行时可以直接读取该属性
print(calculate_tax.__doc__)
此时,这个字符串不会被销毁,而是作为元数据常驻内存,供内置函数 help(calculate_tax)、IDE悬浮文档提示以及 Sphinx 等自动化文档工具生成API文档。
2. 悬空三引号字符串的表现
如果三引号写在普通代码块中间(没有紧跟在定义声明首行,也没有赋值给变量),Python在解析时会将其视作一个匿名的字符串表达式。尽管现代CPython编译器在生成字节码阶段通常会将其作为“无用语句”优化移除,但若它的缩进与当前代码块不一致,程序会在编译期直接崩溃报错 IndentationError。
四、常见避坑场景与开发实用建议
1. 踩坑点一:三引号缩进错误引发 IndentationError
这是三引号充当“临时注释”时最频繁遇到的报错。在带有缩进的代码块(如函数、循环或分支语句)中,三引号的起始和结束引号必须与该代码块的缩进级别完全一致:
def sync_user_profile(user_id):
is_valid = check_id(user_id)
# 错误示例:三引号顶格写,导致解释器报 IndentationError: unexpected indent
"""
临时屏蔽下述同步接口
api.call_remote_sync(user_id)
"""
return is_valid
正确解法:如果使用三引号,每行必须与 is_valid 保持相同缩进;或者直接使用 IDE 快捷键添加连续的 #,后者即使顶格书写也不会引发任何缩进异常。
2. 踩坑点二:误将三引号放在函数第一行破坏原文档
如果在函数内部临时将代码片段用三引号包裹,且恰好位于函数体的第一句,该函数原有的说明文档将被这段临时废弃代码无情覆盖,造成自动化文档混乱。
3. 现代 IDE 快捷键提效技巧
在日常开发中,无需手动逐行敲击 #。主流代码编辑器(如 VS Code、PyCharm、Cursor、Sublime Text)都内置了统一的快捷键:
- Windows / Linux:选中多行代码后按
Ctrl + /,即可一键批量加上或取消#单行注释。 - macOS:选中多行代码后按
Cmd + /进行一键注释与反注释。
五、核心要点总结对照表
| 注释类型 | 对应符号 | 语言机制本质 | PEP 8 推荐建议与适用场景 |
|---|---|---|---|
| 单行注释 | # 文本 |
原生语法注释(词法分析器直接忽略) | 推荐。单行前置说明或行尾解释(行尾需空2格再写#) |
| 多行注释 | 连续每行 # 文本 |
多行原生语法注释 | 官方首选推荐。安全无缩进隐患,适合跨行算法与逻辑推导说明 |
| 文档字符串 | """文本""" 或 '''文本''' |
多行字符串字面量(常驻 __doc__ 属性) |
官方专用规范。用于模块、类、公开函数第一行的 API 文档说明 |
| 临时块注释 | 成对三引号 或 连续 # |
字符串表达式 或 原生注释 | 建议优先用快捷键 Ctrl + / 添加连续 #,避免三引号缩进错误 |
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









