Python注释用什么符号?单行#与多行三引号写法详解

星野
星野
发布时间:2026-11-20| 4人浏览过
原创

详细解答Python注释使用什么符号,系统讲解单行注释井号(#)的基础语法与PEP 8规范、多行三引号('''与""")的本质与区别,以及文档字符串Docstring与常规多行注释的选择建议与常见避坑指南。

核心结论直答:Python官方规定的专属注释符号只有井号(#),它用于单行注释以及由多个单行组成的连续多行注释。对于多行文本说明,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注释用什么符号?单行#与多行三引号写法详解
图 1:Python单行注释书写规范与解释器底层忽略机制

二、多行注释的两种写法:连续井号与多行三引号

当注释内容较多、需要跨越数行进行技术推导或业务解释时,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),它与 # 在底层行为上有着本质区别。

Python注释用什么符号?单行#与多行三引号写法详解
图 2:连续单行井号与三引号多行字符串的语法与运行期差异

三、深度解析:三引号是“真注释”还是“文档字符串”(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。

Python注释用什么符号?单行#与多行三引号写法详解
图 3:Python注释形式选择逻辑与开发决策流程

四、常见避坑场景与开发实用建议

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 + / 进行一键注释与反注释。
Python注释用什么符号?单行#与多行三引号写法详解
图 4:Python注释语法规范、避坑要点与IDE快捷操作全景速查

五、核心要点总结对照表

注释类型 对应符号 语言机制本质 PEP 8 推荐建议与适用场景
单行注释 # 文本 原生语法注释(词法分析器直接忽略) 推荐。单行前置说明或行尾解释(行尾需空2格再写#)
多行注释 连续每行 # 文本 多行原生语法注释 官方首选推荐。安全无缩进隐患,适合跨行算法与逻辑推导说明
文档字符串 """文本""" 或 '''文本''' 多行字符串字面量(常驻 __doc__ 属性) 官方专用规范。用于模块、类、公开函数第一行的 API 文档说明
临时块注释 成对三引号 或 连续 # 字符串表达式 或 原生注释 建议优先用快捷键 Ctrl + / 添加连续 #,避免三引号缩进错误
相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。