搜索菜单
当前位置: 首页 > Python > Python注释符号有哪些？单行#与多行三引号的用法详解

Python注释符号有哪些？单行#与多行三引号的用法详解

Luna
Luna
发布时间：2026-10-24 | 4人浏览过
原创

在 Python 语言中，官方语法层面上唯一的原生注释符号是井号（#）；而初学者常常使用的三引号（''' 或 """），在底层语法中其实是未赋值的多行字符串字面量，当其出现在模块、类或函数的开头时，会成为正式的文档字符串（Docstring）。了解这两者的机制差异、适用场景以及 PEP 8 编码规范，不仅能帮助你写出结构清晰的代码，还能避免因缩进与内存驻留引发的隐蔽错误。本文将为你系统梳理 Python 注释的核心符号、具体操作示例与规范用法。

一、Python 注释符号概览与核心机制

编写程序时，注释用于解释代码的设计目的、业务背景或算法逻辑，Python 解释器在执行代码时会对它们采取不同的处理方式。要准确掌握 Python 注释，首先需要理清真正的注释语法与多行字符串之间的本质差别：

  • 真正注释符号（#）：从井号开始一直到当前行末尾的所有字符，在 Python 的词法分析阶段（Lexing/Tokenizing）就会被完全忽略，既不会生成任何底层字节码，也不会占用运行时的内存资源。
  • 多行字符串符号（''' 或 """）：成对出现的三个单引号或三个双引号。虽然它们经常被用作临时注释大段代码的手段，但在 Python 编译器眼中，它们是合法的字符串表达式。只有当其位于模块、类、方法的第一行作为接口说明时，才具有特殊的语言意义（绑定到 __doc__ 属性）。
Python注释符号有哪些？单行#与多行三引号的用法详解
图 1：Python 注释符号分类与底层机制对比

二、单行注释（#）的具体用法与场景

单行注释是 Python 中最常用、最标准的代码批注形式。在实际开发中，单行注释主要分为两种摆放形式：独立单行注释与行尾注释。

1. 独立单行注释（Block Comments）

独立单行注释通常单独占据一行，紧贴在其所要解释的代码段落之前。它适合对接下来一段较为复杂的运算、状态流转或边界判断提供概括性说明。

# 校验用户输入的数据完整性，若缺少必要字段则提前抛出异常
if not payload.get("username") or not payload.get("token"):
    raise ValueError("缺少必要的身份鉴权参数")

按照 PEP 8 规范，独立注释的 # 符号后必须紧跟一个英文空格，然后书写注释文字。如果多行连续解释，每一行开头都必须拥有一个 # 和一个空格。

2. 行尾注释（Inline Comments）

行尾注释位于代码语句的同一行右侧，紧跟在表达式之后。这种形式通常用于对某个特定变量、常量参数或边界值进行微观补充说明。

MAX_RETRY_TIMES = 3  # 网络不稳定时的最大重试上限
timeout_seconds = 15  # 单次连接超时时间（秒）
PEP 8 行尾注释规范要点：
  1. 代码与 # 之间必须保留至少两个空格，避免注释与代码粘连，保证横向视觉分隔。
  2. # 与注释内容之间必须保留一个空格。
  3. 避免对显而易见的代码写无意义的行尾注释（如 i = i + 1 # 变量i自增1），行尾注释应该解释“为什么设置这个值”。

三、多行注释的两种实现方式及优劣对比

Python 并没有像 C 或 Java 中 /* ... */ 形式的原生专用多行注释符号。在实际开发中，开发者通常有两种方式实现多行内容的批注：

方式一：连续单行井号（#）—— PEP 8 官方推荐

在每一行的起始位置都放置一个 #，这是 Python 社区与官方文档最为推荐的多行注释组织形式。各大主流编辑器（如 VS Code、PyCharm）均支持快捷键批量添加或取消（Windows/Linux 下使用 Ctrl + /，macOS 下使用 Cmd + /）。

# 计算订单最终实付金额：
# 1. 首先应用全场满减券
# 2. 扣除会员积分抵扣额度
# 3. 计入偏远地区额外物流费用
final_amount = calculate_final_price(order)

方式二：成对的三引号（''' 或 """）作为块注释

三引号常被用来快速注释掉一大段现存的代码块或编写大段说明。由于 Python 解释器在读取未被任何变量接收、未被任何函数调用的裸字符串常量时，默认不会对其执行操作，因此它在功能上达到了“代码被忽略”的效果。

"""
注意：以下函数接口已废弃，仅保留用于向下兼容 v1.2 客户端。
新功能请直接迁移至 query_user_v2 接口。
"""
def legacy_query_api():
    pass

需要特别注意：三引号字符串在语法分析器中仍是合法的 AST 表达式节点。如果将三引号放在缩进的代码块中，三引号本身的缩进层级必须与上下文代码严格一致。若缩进错乱，程序会直接报错终止运行。

Python注释符号有哪些？单行#与多行三引号的用法详解
图 2：PEP 8 规范下的 Python 注释编写四步法流程

四、三引号的正式使命：文档字符串（Docstring）详解

既然官方不提倡把三引号当作日常业务逻辑的注释，那么三引号最正统的使用场景是什么？答案是：文档字符串（Docstring，PEP 257 规范）。

当三双引号（"""）紧跟在模块、类定义或函数定义的第一行时，Python 解析器会自动将其捕获并赋值给该对象的 __doc__ 特殊属性。这一机制具有双重价值：

  1. IDE 智能提示：其他开发者在调用该函数时，代码补全插件能实时弹出包含参数说明、返回值与异常信息的浮窗。
  2. 自动化文档构建：工具（如 Sphinx、pydoc、MkDocs）可以直接遍历代码，提取这些 Docstring 自动生成离线 API 技术手册。

1. 单行 Docstring 标准格式

适用于极其直观简短的函数。总结语句放在同一行，首尾引号均不换行，末尾带有句号。

def add(a: int, b: int) -> int:
    """计算并返回两个整数相加之和。"""
    return a + b

2. 多行 Docstring 标准格式

适用于具有入参、出参和潜在异常的复杂模块或方法。一般采用以下组织架构：

def fetch_resource(url: str, retry: int = 3) -> dict:
    """通过 HTTP GET 请求检索指定的远端 JSON 数据对象。

    当网络发生瞬时抖动时，函数会按指数退避算法自动进行重试，
    直至达到最大重试次数上限。

    参数：
        url (str): 远端接口的完整合法 URL 地址
        retry (int, 可选): 最大允许尝试请求的次数，默认为 3 次

    返回：
        dict: 接口反序列化解析后的数据负载字典

    异常：
        ConnectionError: 当超过最大重试次数仍连接失败时抛出
    """
    # 此处放置具体的执行逻辑
    pass

3. 如何在交互式环境中查看 Docstring

在 Python REPL 交互环境或终端命令行中，可以通过内置的 help() 函数或直接读取 __doc__ 属性检验成果：

# 查看内置函数或自定义函数的文档
>>> help(fetch_resource)

# 或者直接打印属性内容
>>> print(fetch_resource.__doc__)

五、PEP 8 注释规范与常见错误避坑指南

PEP 8（Style Guide for Python Code）是 Python 官方制定的风格指南。糟糕的注释排版会降低代码可读性，以下是开发中最容易出现的四类错误及其修正方案：

Python注释符号有哪些？单行#与多行三引号的用法详解
图 3：PEP 8 注释规范正确做法与典型反模式对比

1. 陷阱一：三引号缩进错误（IndentationError）

当开发者在缩进的代码块内部（如 if 分支或函数体）随意粘贴未对齐的三引号时，由于三引号本质是字符串表达式，Python 的缩进解析器会立即抛出异常：

def process_data(items):
    for item in items:
# 错误示范：左顶格放置三引号，破坏循环内部缩进
"""
这里临时测试注释
item.clean()
"""
        item.save()  # 触发 IndentationError: unexpected indent

避坑指南：临时屏蔽代码请使用 IDE 的 # 批量注释功能，或确保三引号的左右缩进与 item.save() 完全一致。

2. 陷阱二：废话注释与视线噪音

很多初学者喜欢对每一行代码都加上机械式说明：

# 错误示范：毫无信息增量的废话注释
name = input()  # 获取用户输入
print(name)  # 打印用户名字

好的注释应该回答Why（设计决策、业务理由、特殊边界处理），而不是翻译How（语法本身的动作）。

3. 陷阱三：特殊场景的声明式注释

在 Python 体系中，有一类特殊的 # 注释是会被工具链或运行时解析的，具有特定语义：

  • 编码声明注释（Python 2 遗留，Python 3 默认 utf-8，但在旧文件仍常见）：
    # -*- coding: utf-8 -*-
  • 解释器路径声明（Shebang）（用于 Unix/Linux 下直接执行脚本）：
    #!/usr/bin/env python3
  • 类型检查器忽略标记（告诉 Mypy 等工具忽略该行类型警告）：
    result = unsafe_call() # type: ignore
  • 代码格式化忽略标记（告诉 Black 或 Flake8 跳过检查）：
    # noqa: E501

六、选型指南与全场景速查总结

为了在实际写代码时能快速作出决策，下表与决策树汇总了不同场景下的最佳注释符号选型：

注释目标与应用场景 推荐符号 / 方式 底层本质 规范建议
函数、类、模块接口说明 成对三双引号 """...""" Docstring（绑定到 __doc__） 遵循 PEP 257 规范，写明参数、返回值及异常
单行逻辑说明、行尾备注 单行井号 # 词法级注释（完全被编译器忽略） # 后空一格；行尾离代码至少空两格
算法步骤、长段代码解释 多行连续井号 # 词法级注释（零内存开销） 每行独立 #，单行不超过 72 字符，IDE快捷键操作
临时大段屏蔽调试代码 IDE 批量 #（次选三引号） 词法级注释 / 孤立常量表达式 提交代码库前务必清理，若用三引号严防缩进错乱
Python注释符号有哪些？单行#与多行三引号的用法详解
图 4：Python 注释方式选用决策树与速查总结

总结来说，Python 代码中的注释虽小，却直接影响团队协作效率与代码维护质量。记住两个核心准则：解释接口对外能力时使用三双引号（Docstring），解释代码对内实现与关键细节时使用单行井号（#）。遵从 PEP 8 的排版与空格要求，及时更新或清理与代码不匹配的旧注释，才能写出既整洁专业、又经得起时间考验的 Python 程序。

相关文章

相关标签: Python docstring

本站声明

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

作者最新文章

全部内容

Python 相关产品和应用

全部下载
Python Selenium
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。
Python 机器学习 Scikit-learn
scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。
Python 代码质量
Black

Black

26.10.1 · Windows

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

Ruff

0.17.1 · macOS

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

pytest

9.1.1 · Windows

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

FastAPI

0.146.0 · Windows

高性能 Python API 框架，支持类型提示和自动接口文档。
Python Flask Web开发
Flask

Flask

3.1.3 · Windows

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

Django

6.1.2 · Windows

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

Spyder

6.1.7 · Windows

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

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。
Python Pandas 数据分析
pandas

pandas

3.0.6 · Windows

Python 数据分析库，提供 DataFrame 与丰富的数据处理能力。
Python NumPy
NumPy

NumPy

2.5.4 · Windows

Python 科学计算基础库，提供高性能多维数组与数值运算。

文章分类

专题列表

ipython.cn 学习网
人工智能 Java AI行业服务