Python注释符号怎么写：单行#与多行三引号用法

在 Python 中，注释是让代码更易维护和协作的核心工具。Python 官方并没有专门为“多行注释”定义单独的语法符号，最直接、标准的注释方式是使用井号 #；对于跨越多行的文本说明，通常采用连续多行 # 或未分配给变量的三引号字符串（''' 或 """）。理解它们的书写格式、快捷操作与底层行为差异，能够帮助开发者写出符合 PEP 8 规范且逻辑严谨的代码。

一、单行注释（#）的标准写法与操作步骤

单行注释以井号 # 开头，井号之后直到该行末尾的所有字符都会被 Python 解释器直接忽略。单行注释主要分为“独立成行”和“行尾注释”两种形式，在编写时需要遵循标准的排版规范以保证可读性。

1. 独立单行注释

独立单行注释通常置于被解释代码段的正上方。按照 PEP 8 规范，# 符号与后面的注释文字之间必须保留一个空格，使视觉结构清晰分明：

# 计算圆的周长与面积
radius = 5.0
perimeter = 2 * 3.14159 * radius
area = 3.14159 * (radius ** 2)

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

行尾注释位于单行有效代码的末尾。为了避免注释与逻辑代码混淆，规范要求 # 距离前面的代码至少保留两个空格，# 后面同样空一格。行尾注释应当只用来补充“为什么这么写”，而不是复述代码本身已经表达的逻辑：

timeout = 30  # 设置较长超时以适应弱网环境
status_code = 200  # HTTP 成功响应状态码

3. IDE 中的快捷注释操作

在主流 Python 编辑器（如 PyCharm、VS Code）中，不需要手动逐行敲入井号。选中目标行后，按下快捷键即可自动批量添加或移除 #：

• Windows / Linux：选中代码后按 Ctrl + /
• macOS：选中代码后按 Cmd + /

二、多行注释与三引号（''' / """）的机制与用法

在 Python 语法层面，三引号 ''' 或 """ 本质上是多行字符串字面量（Multi-line String Literal）。当一个多行字符串没有赋值给任何变量，也没有作为参数传递给函数时，它在语法树中仅作为一个独立的常量表达式存在。

1. 连续井号与三引号的对比写法

编写多行说明时，官方 PEP 8 推荐首选连续单行注释：

# 本函数负责读取配置文件并校验格式
# 若文件缺失则回退到默认字典
# 参数 config_path 必须为合法系统路径
def load_settings(config_path):
    pass

也可以使用多行三引号包裹文本：

"""
本模块为数据处理管道
包含清洗、过滤及聚合三阶段
适用于离线批处理任务
"""
import os

2. 解释器对两种注释的处理原理

# 与未赋值的三引号字符串在 Python 解释器内部的处理流程存在根本差异：

• 井号注释：在词法分析阶段（Tokenize）就被词法分析器作为 COMMENT 标记直接滤除，不会进入抽象语法树（AST），编译后生成的 .pyc 字节码中没有任何痕迹。
• 未赋值三引号字符串：词法分析阶段会被识别为 STRING，并作为 Constant 表达式挂载到 AST 上。在随后的代码生成和优化阶段，编译器识别出该常量表达式既无副作用也无赋值引用，因此在最终生成的字节码中将其丢弃（若在模块、类或函数首行，则会被特殊保留为文档字符串）。

三、文档字符串（Docstring）与普通注释的关键区别

初学者容易将三引号当作单纯的多行注释，但三引号在 Python 中有一项非常重要的系统级功能：定义文档字符串（Docstring）。

当三引号紧跟在模块、类（Class）或函数（Function）定义的第一行时，它就成为该对象内建的文档字符串，Python 会在运行时自动将其绑定到该对象的 __doc__ 属性上。开发工具、自动文档生成器（如 Sphinx）以及内置函数 help() 都会读取这一属性。

def calculate_tax(amount, rate=0.05):
    """
    计算应纳税额。

    参数:
        amount (float): 原始金额，需大于等于 0
        rate (float): 税率，默认 0.05 (5%)

    返回:
        float: 计算后的税费总额
    """
    # 业务校验：负数金额直接抛出异常
    if amount < 0:
        raise ValueError("金额不能为负数")
    return amount * rate

# 运行时读取文档字符串
print(calculate_tax.__doc__)

如果三引号放在函数体中间，或者前方已有普通执行语句，它便退化为普通的未引用字符串表达式，无法被 __doc__ 访问。

四、常见易错点与注意事项

在实际编码中，错误使用注释符号容易导致语法错误或文档污染，以下是三个最为典型的问题：

# 错误示范：三引号顶格导致缩进破坏
def query_user():
"""
临时跳过这几行执行
print("正在执行查询...")
"""
    return {"id": 101}  # 报错：IndentationError

# 正确写法：三引号与所在代码块缩进严格对齐
def query_user():
    """
    临时跳过这几行执行
    print("正在执行查询...")
    """
    return {"id": 101}

五、总结：Python 注释方式选用决策树

为了在团队开发中保持整洁一致的代码风格，可以根据下表和决策树快速选择合适的注释方式：