Python单行与多行注释怎么写

何川

发布时间：2026-10-20 | 6人浏览过

原创

在 Python 中，单行注释使用井号（#）开头；对于多行注释，官方 PEP 8 规范推荐使用连续的多行 # 来书写。此外，三引号包裹的多行字符串（""" 或 '''）在不赋值给变量时，也常被开发者用作多行注释，特别是在为模块、类或函数定义文档字符串（Docstring）时。掌握这两种注释的语法细节、底层差异与书写规范，是编写清晰、整洁 Python 代码的基础。

一、Python单行注释的书写方法与规范

单行注释是 Python 中最常用的注释形式。Python 解释器在词法分析时，一旦遇到未包含在字符串内的井号字符 #，就会忽略该行中从 # 开始一直到行末的所有内容。单行注释通常有两种出现形式：独立行注释与行尾（行内）注释。

1. 独立行注释

独立行注释独占一行，通常放在被解释代码的上方。根据 PEP 8 规范，# 后面应当紧跟一个半角空格，然后再书写注释文字；同时，注释行的缩进层级必须与所修饰的代码块保持严格一致。

# 计算订单总金额（包含基础运费）
base_shipping_fee = 15
subtotal = 120
total_price = subtotal + base_shipping_fee

def calculate_discount(price):
    # 达到满减门槛后统一折减 20 元
    if price >= 100:
        return price - 20
    return price

2. 行尾注释（行内注释）

行尾注释与代码位于同一行，紧跟在代码语句之后。编写行尾注释时，PEP 8 规范提出了两条明确的格式建议：

代码末尾与 # 之间，至少保留两个半角空格，以确保代码与注释在视觉上有清晰的分隔；
# 与随后的注释文本之间，保留一个半角空格；
仅在解释特定参数、边界值或非显而易见的逻辑时使用，避免每一行都添加行尾注释导致代码版面杂乱。

threshold = 80  # 判定为优质客户的分数阈值
timeout_seconds = 5  # 网络请求超时上限，单位为秒

图 1：Python 单行注释（独立行与行尾）的书写操作流程与排版规范

二、Python多行注释的两种书写方式与本质差异

与其他语言（如 C/C++ 或 Java 的 /* ... */）不同，Python 原生语法中并没有专门的“块注释定界符”。在实际开发中，开发者通常有两种实现多行注释的途径：

1. 方式一：连续使用多个单行注释 `#`（官方推荐）

这是 Python 官方 PEP 8 风格指南明确推荐的多行注释写法。每一行注释文本的开头都放置一个 # 和一个空格。多行之间如果要分段，中间可以放置一个仅包含 # 的空注释行。

# 数据预处理模块
# 该函数负责读取原始日志文件，过滤非法字符，
# 并将时间戳格式化为 UTC 标准时间。
#
# 注意：若日志包含未闭合引号，则整条记录将被抛弃。
def process_access_log(file_path):
    pass

使用连续 # 的最大优势在于词法纯洁性：Python 解释器在编译生成字节码之前，就会在词法分析阶段彻底丢弃这些字符，编译出的 .pyc 文件中不会包含任何此类注释数据，因此在运行时完全没有内存与性能负担。

2. 方式二：使用未赋值的三引号多行字符串（`"""` 或 `'''`）

在 Python 中，成对出现的三个单引号 ''' 或三个双引号 """ 可以定义跨越多行的多行字符串。如果将一个三引号字符串独立放置，且没有将其赋值给任何变量，也没有作为表达式传递给函数，Python 解释器在语法上允许其存在，并在执行时忽略其副作用。许多开发者利用此特性将其作为快速屏蔽多行代码或书写长篇说明的方式。

"""
这是一个临时被停用的模块配置。
在旧版接口迁移完成之前，请勿开启以下参数。
支持批量调试与历史数据重放。
"""
ENABLE_LEGACY_SYNC = False

注意：三引号字符串虽然常被借用为多行注释，但它在 Python 语法树中本质上仍是一个字符串字面量（String Literal）。如果缩进不当，它会直接触发 IndentationError（缩进错误）。

图 2：连续单行 # 注释与三引号字符串在编译期、运行期及用途上的差异对比

三、文档字符串（Docstring）与普通多行注释的明确分工

当三引号多行字符串出现在模块、类、方法或函数定义的第一行时，它就拥有了特殊的身份——文档字符串（Docstring）。

1. Docstring 的运行时访问能力

与普通注释在编译期被彻底剔除不同，作为 Docstring 的三引号字符串会被 Python 解释器保存在该对象的 __doc__ 属性中，可以通过代码直接读取，也能被内置的 help() 函数以及 Sphinx 等文档自动生成工具所解析。

def get_user_profile(user_id: int) -> dict:
    """根据用户唯一标识获取个人主页基础信息。

    参数:
        user_id (int): 数据库中的用户自增ID。

    返回:
        dict: 包含用户名、头像地址及注册状态的字典。
    """
    # 这一行是普通单行注释，不会进入 __doc__
    return {"id": user_id, "status": "active"}

# 在运行时直接查看该函数的文档字符串
print(get_user_profile.__doc__)

2. 选型指南：什么时候用连续 #，什么时候用 Docstring？

使用 Docstring（三引号）：用于向调用者解释模块、类、接口或函数的“外部契约”——说明它的功能是什么、接收哪些参数、返回什么结果、可能抛出什么异常。
使用连续 #：用于解释代码内部的“具体实现细节”——为什么使用这种算法、某些复杂数学公式的推导依据、临时修复特定 bug 的绕过逻辑等。这类内容属于内部实现，不应当暴露在给外部调用的 __doc__ 中。

图 3：根据注释目标、作用域与生命周期选择最合适的注释形式

四、PEP 8 注释规范与常见编写误区

掌握了注释语法之后，如何写出高质量、易维护的注释同样关键。Python 官方 PEP 8 风格指南对注释提出了具体的质量要求：

1. 常见误区与反面教材

误区类型	不良示例	规范做法及改进理由
复述代码字面	`count += 1 # 变量count加1`	无需注释。好代码本身自解释，注释应说明“为什么加1”（如：`count += 1 # 计入跳过重试的次数`）。
注释与代码脱节	修改了业务逻辑，但遗留了旧注释。	过时或错误的注释比没有注释危害更大。重构代码时，必须优先检查并同步修正相关注释。
三引号缩进错误	在缩进块内把三引号顶格书写。	三引号字符串仍须遵守所在代码块的缩进层级，否则会直接引发 `IndentationError`。
大面积残留死代码	代码库中充斥几十行被 `#` 注释掉的废弃代码。	现代项目已全面普及 Git 等版本控制工具。废弃代码应直接删除，不必靠注释存档。

2. PEP 8 核心要点速查

行长限制：注释行的单行最大长度建议限制在 72 个字符以内（相比代码的 79 字符更紧凑），以便在分屏阅读时完整呈现。
标点与完整性：块注释建议采用完整句子书写，句子末尾加上句号；若是多句组成的段落，句与句之间保持规范空格。
中文注释规范：中文与英文单词、数字混排时，两端保留一个半角空格，排版更具呼吸感（例如：# 解析 JSON 响应中的 code 状态码）。

图 4：Python 注释规范、文档约束及长期维护最佳实践总结面板

五、总结

编写 Python 注释的核心要点可以概括为：

单行注释：使用 # 开头，并紧跟一个空格；行尾注释在代码后留两个空格，简要说明临界逻辑。
多行注释：日常逻辑说明推荐使用连续的多行 #，干净、规范且零运行时开销。
文档说明：对模块、类、函数撰写对外接口文档时，规范使用三双引号 """ 的 Docstring，便于运行时 __doc__ 访问与文档工具集成。
维护原则：注释重在阐述设计意图和原因，代码更新时必须同步维护注释，确保注释与真实运行逻辑始终一致。