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

一、单行注释井号（#）的语法机制与规范

井号 # 是 Python 词法分析器（Lexer/Tokenizer）中原生定义的注释起始标记。从代码中的 # 开始，整行后续的所有文本都会被标记为 COMMENT 标记，并在构建抽象语法树（AST）之前被编译器完全忽略。这意味着注释不会生成任何字节码（Bytecode），运行时不消耗内存，也不会对程序的运行速度产生任何副作用。

1. 单行注释的四种常见应用形态

在日常开发与工程实践中，# 通常出现在以下四种场景中：

• 文件头部解释器与编码声明：置于源文件第 1 行或第 2 行。Unix/Linux 环境下的 Shebang 声明（例如 #!/usr/bin/env python3）让脚本具备直接可执行属性；编码声明（例如 # -*- coding: utf-8 -*-）用于告知加载器文本字符集（Python 3 默认即为 UTF-8）。
• 独立块注释（Block Comments）：通常位于一段逻辑代码的上方，用来解释紧随其后的代码意图或实现思路。块注释必须与被注释的代码保持完全相同的缩进。
• 行尾注释（Inline Comments）：写在可执行语句同一行的末尾。它只应当用于解释非显而易见的变量含义或业务约束，避免复述代码字面逻辑。
• 代码调试与临时屏蔽：在排查问题时临时禁用某一行或几行逻辑，无需删除原始代码即可观察运行变化。

2. PEP 8 对井号注释的书写格式规范

官方 Python 风格指南（PEP 8）对 # 的排版提出了明确的要求，遵循这些规范可以显著提升代码的可读性：

• 符号后的空格：# 后面必须紧跟一个半角空格，然后再书写注释文字（例如 # 这是正确格式，而不是 #这是错误格式）。Shebang 与编码声明属于特殊元指令，不受该空一格规则限制。
• 行尾注释间距：如果将注释放在代码同行右侧，代码末尾与 # 之间必须至少保留两个半角空格，避免注释与有效代码挤在一起引发视觉混乱。
• 缩进必须对齐：块注释的缩进层级必须与所修饰的代码段完全一致。虽然缩进不对齐的 # 不会导致解释器报错，但会破坏代码结构的层次感。

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

def calculate_discount(price, level):
    # 针对不同会员等级计算对应折扣比例
    # 非会员默认不打折，黄金会员享受 85 折
    if level == "gold":
        rate = 0.85  # 黄金会员基准费率（留出两格空格）
    else:
        rate = 1.0   # 基础无折扣费率
    
    return price * rate

二、多行三引号：为什么常被当成注释？它的本质是什么？

在 C、Java、JavaScript 等语言中，存在成对的 /* ... */ 语法用于包裹多行注释。很多初学者在转到 Python 时会发现：Python 并没有专门的多行注释定界符号。取而代之的是，社区和各类教材中普遍使用成对的三单引号 ''' 或三双引号 """ 来包裹多行说明文字。

1. 语法底层：未赋值的字符串字面量

从 Python 语言规范的角度看，三引号包裹的文本在词法阶段被解析为 STRING 标记，本质上是多行字符串字面量（Multi-line String Literals）。在 Python 语法中，任何合法的表达式都可以作为独立的一条语句（Expression Statement）存在：

def example():
    42                  # 未赋值的整型字面量，合法但无意义
    "hello world"       # 未赋值的单行字符串，合法但无副作用
    """
    这里是一段未赋值的多行字符串
    由于没有被赋值给变量，也没有被函数消费
    在实际效果上常被用作大段注释
    """
    return True

当一段三引号字符串没有被赋值给任何变量、也没有传入任何函数时，Python 字节码编译器的常量优化机制（Constant Folding / AST Optimization）通常会在生成 .pyc 文件时将其剔除，因此在绝大多数情况下不会带来多余的性能开销。这也是三引号能够“假借”为多行注释的原因。

2. 文档字符串（Docstring）与注释的本质分水岭

虽然三引号看起来与注释效果类似，但在 Python 中，它承担着一项官方专门赋予的特殊使命——文档字符串（Docstring）：

• 触发条件：当三引号字符串出现在模块、类、方法或函数定义的第一行有效可执行语句位置时，解释器不会将其视作无用语句丢弃。
• 绑定机制：解释器会将这段字符串自动编译并绑定到对应对象的 __doc__ 内部属性中。
• 运行时存留：Docstring 会伴随该对象一直常驻在内存中，可通过 help(obj) 或 obj.__doc__ 动态查看，自动化文档生成工具（如 Sphinx、pydoc）也是依赖该机制提取 API 文档的。

def fetch_user_profile(user_id: int) -> dict:
    """通过用户 ID 查询完整的用户画像数据。
    
    参数:
        user_id: 用户的唯一整型数字 ID
    返回:
        包含用户详细基础属性与权限集合的字典
    """
    # 此处的 # 才是纯正的代码注释，不会存入 __doc__
    return {"id": user_id, "role": "viewer"}

# 运行时可动态获取 Docstring:
# print(fetch_user_profile.__doc__) 输出上述文档内容

三、常见易混淆说法辨析与潜在陷阱

在关于 Python 注释的讨论中，有几个经常被提及但并不准确的说法，极容易误导初学者。通过明确其成立条件与边界，有助于掌握规范的编写方法。

# 错误示例：缩进不一致引发语法崩溃
def process_order():
    status = "pending"
"""
注意：这里的三引号顶格书写（缩进为 0）
直接破坏了函数内部应保持的 4 空格缩进层级！
运行结果: IndentationError: unexpected indent
"""
    return status

四、工程实战：注释选型流程与操作建议

面对具体的开发任务，何时使用单行 #、何时编写连续的 # 代码块、何时采用三引号 Docstring？可参考下方的选型决策流程。

1. 编写说明的标准步骤

1. 确认受众与目标：如果是对模块、类、函数的入参、返回值或对外使用协议进行定义，受众是该函数或模块的使用者，请毫不犹豫地使用三双引号 """ 编写规范的文档字符串（Docstring），并将其紧放在 def 或 class 的下一行。
2. 内部业务逻辑说明：如果注释是写给代码维护者看的实现细节、算法推演、逻辑分支原因，优先选择单行或多行连续的 #。
3. 多行屏蔽代码的高效操作：不要手动在每行敲 #，也不建议包裹三引号。在现代主流代码编辑器（VS Code、PyCharm、Sublime Text）中，鼠标选中需要注释的多行代码，直接按下通用快捷键：
   • Windows / Linux：Ctrl + /
   • macOS：Cmd + /
   编辑器会自动为选中的每一行添加或移除 #，并自动匹配缩进，既安全又符合 PEP 8 规范。

五、全景特征对比与核心总结

为了直观掌握 Python 中不同注释方式的技术差异，下表汇总了其在词法地位、运行时表现、缩进限制及推荐场景上的关键区别：