Python有多行注释符吗？澄清/* */误区与正确写法

Evan

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

原创

在 Python 语言中，没有专门的独立多行注释符。C、C++、Java、JavaScript 等语言中常见的块注释标记 /* ... */ 在 Python 中并不存在，若在代码中书写会直接引发语法错误。Python 语法中唯一官方认可的原生注释符号是半角井号 #。在实际工程与代码规范中，多行注释是通过连续的多行单行注释来实现的。

许多初学者乃至有一定开发经验的程序员，习惯使用三引号（""" 或 '''）来包裹多行文字充当“多行注释”。这种做法在许多场合下虽然程序能跑通，但它在 Python 底层并不是注释，而是未赋值的字符串字面量（String Literal）。理解这一机制差异，对于写出规范、健壮的 Python 代码至关重要。

Python有多行注释符吗？澄清/* */误区与正确写法 — 图 1：Python 注释语法形态与底层机制对比，明确井号的唯一合法性与三引号的真实身份

澄清误区一：为什么在 Python 中写 /* */ 会直接报错？

习惯了 C、C++、Java、Go 或 JavaScript 的开发者在初学 Python 时，常会下意识输入 /* 注释内容 */。但在 Python 解释器看来，这并不是注释标记，而是非法的数学运算符组合。

在 Python 的词法分析阶段，斜杠 / 被定义为浮点除法运算符，星号 * 被定义为乘法或解包运算符。当代码行首出现 /* 时，词法分析器不会将其作为一个整体记号（Token）识别，而是分别识别为一个除号和一个乘号。因为前面没有任何可以参与运算的变量或数字，语法解析器会立刻判定该表达式结构非法，并抛出 SyntaxError（语法错误）。

# 错误示例：试图在 Python 中使用 C 语言块注释风格
/*
这是一个多行注释示例
计算两个数字的和
*/
def add(a, b):
    return a + b

执行上述代码时，Python 解释器在编译第一行就会直接终止并报错：

  File "main.py", line 1
    /*
    ^
SyntaxError: invalid syntax

关键认知：Python 没有任何以斜杠或星号组合开头的注释语法。无论在单行还是跨多行，遇到类似需求都必须使用 #。

澄清误区二：三引号 """ 到底算不算多行注释？

网络上许多教程会将包裹在三个双引号（"""）或三个单引号（'''）之间的文本称为“Python 多行注释”。这种说法在教学中看似让初学者更容易接受，但从语言规范和执行原理上看，它并不是真正的注释。

1. 为什么它看起来像注释？

在 Python 中，如果一个表达式语句（Expression Statement）只包含一个字符串字面量，且没有被赋值给任何变量，也没有作为参数传入任何函数，那么在代码运行时，它确实不会产生任何可视的输出或改变程序的运算结果。例如：

def calculate_area(width, height):
    """这是一段未赋值的多行字符串
    程序运行到这里不会打印任何信息
    也不会影响下面的乘法运算"""
    return width * height

由于代码执行时没有报错，初学者很容易形成“三引号就是多行注释”的直观印象。

2. 底层机制上的三大本质区别

虽然表面上没有报错，但解释器对三引号字符串与真正的 # 注释的处理流程截然不同：

词法分析与语法检查：真正的注释 # 在词法扫描（Tokenize）阶段就会被直接丢弃，根本不会进入语法分析树（AST），也不会经历任何语法校验。而三引号是一个正规的字符串字面量，必须符合 Python 字符串的所有语法规则。如果三引号内部包含不合法的反斜杠转义字符或引号未闭合，解释器在解析阶段就会直接抛出错误。
严格的代码缩进约束：# 可以在任意列自由书写，不会破坏代码块结构。但三引号字符串作为合法的 Python 语句，必须遵守当前代码块的严格缩进规则。如果在缩进块内部没有正确对齐首尾引号，会导致 IndentationError（缩进错误）。
文档字符串（Docstring）的特殊用途：当三引号字符串紧跟在模块、类或函数的首部时，Python 会将其提取为该对象的元数据，保存在 __doc__ 属性中，并常驻内存供 help() 等反射工具调用。此时它具有明确的运行时意义，绝非被忽略的注释。

正确规范：Python 官方推荐的多行注释写法

在 Python 官方代码风格指南（PEP 8）中，对多行注释（块注释，Block Comments）有明确的标准指导：块注释通常适用于跟随其后的一些或所有代码，并缩进到与该代码相同的级别。块注释的每一行都以 # 和一个空格开头。

1. 标准连续单行注释写法

当需要书写长篇文字对算法、业务背景或复杂判断逻辑进行说明时，标准写法是使用多行连续的 #。如果说明文字较长需要分段，段落之间应使用一个只包含 # 的空行来分隔：

# 校验用户提交的表单数据是否符合安全规范。
#
# 首先核对用户名长度与字符集白名单，杜绝 SQL 注入隐患；
# 其次检查密码强度评分，若低于安全阈值则阻止提交；
# 最后比对图片验证码的时间戳，防止重放攻击。
def validate_user_registration(form_data):
    # 第一步：核对用户名
    if not check_username(form_data.get("username")):
        return False, "用户名格式不合法"
    
    # 第二步：核对密码强度
    if not check_password_strength(form_data.get("password")):
        return False, "密码安全等级过低"
        
    return True, "验证通过"

这种写法的优势在于：

所有工具和解析器百分之百识别为注释，不产生任何语法误判。
不参与字符串转义解析，在注释中书写反斜杠路径（如 C:\Users\Admin）或包含各种引号时，绝不会引发解码异常。
在代码折叠或重构时，语义边界清晰稳定。

2. 文档字符串（Docstrings）的标准写法

三引号字符串有其自身正统、关键的职责，即编写文档字符串（Docstring）。它用于向外部调用者解释模块、类、方法或函数的接口契约：

def get_user_profile(user_id: int) -> dict:
    """根据用户唯一标识查询详细资料。

    参数:
        user_id (int): 用户的全局唯一数字标识编号。

    返回:
        dict: 包含用户名、邮箱、注册时间等信息的字典对象。

    异常:
        ValueError: 当传入的 user_id 不是有效正整数时触发。
    """
    if user_id <= 0:
        raise ValueError("用户ID必须大于零")
    return fetch_from_database(user_id)

通过这种方式编写的说明，可以使用 Python 内置的 help(get_user_profile) 查阅，也会被自动化文档工具精准提取。

效率技巧：主流编辑器中的“一键多行注释”

很多开发者之所以倾向于使用三引号当多行注释，很大程度上是因为觉得每行手动输入 # 比较繁琐。实际上，所有主流开发工具都内置了多行批量注释的快捷键：

开发工具 / 编辑器	Windows / Linux 快捷键	macOS 快捷键	实际执行动作
Visual Studio Code	`Ctrl + /`	`Cmd + /`	在选中的每一行行首批量添加或移除 `#`
PyCharm / IntelliJ IDEA	`Ctrl + /`	`Cmd + /`	在选中的每一行行首批量添加或移除 `#`
Sublime Text	`Ctrl + /`	`Cmd + /`	选中区域批量行注释切换
Jupyter Notebook / Lab	`Ctrl + /`	`Cmd + /`	单元格选中代码批量切换 `#` 注释

值得注意的是，即便在 PyCharm 等 IDE 中按下专门的块注释快捷键（如 Ctrl + Shift + /），针对 Python 文件，IDE 同样是在每行行首插入 #，而不会插入 /* */。这从开发工具链的设计上进一步证明了：在选区中批量添加井号，就是 Python 世界里标准的多行注释实现方式。

实战排坑：三引号充当注释时的典型隐患

为了加深理解，我们来看两个在实际开发中使用三引号代替注释时极易触发的真实排坑案例：

案例一：缩进未对齐引发 IndentationError

# 开头的行哪怕没有和内层代码对齐，通常也不会破坏代码结构；但三引号是语句，如果在分支内部随手写三引号却没有保持缩进，代码将无法运行：

def process_items(items):
    for item in items:
        # 下方如果用三引号，且左对齐顶格书写：
"""
这里临时写了一段三引号文字
起止没有按照 for 循环缩进 8 个空格
"""
        print(item)

执行该文件时，解释器会在后续代码行抛出：

IndentationError: unexpected indent

案例二：转义字符导致语法解析异常

如果使用三引号去临时注释一段包含 Windows 绝对路径或特殊反斜杠的代码，会意外触发转义错误：

"""
临时停用此段配置：
path = "C:\user\test\new_file.txt"
"""

在较新的 Python 版本中，未加原始字符串标识 r 的字符串若包含无法识别的转义字符（如 \u 后未接合法十六进制字符），会直接触发 SyntaxError: (unicode error) 'unicodeescape' codec can't decode bytes...。而使用 # 进行整行注释时，井号后整行内容被词法阶段完全忽略，永远不会遇到此类问题。

总结与速查清单

梳理 Python 注释的核心规则，可以归纳为以下三点黄金法则：

无独立块注释符：Python 官方语法中只有单行注释符 #，不存在类似 C 语言的 /* ... */，切勿在 Python 文件中使用。
多行注释用连续 #：长篇算法说明、业务流程解释，一律采用连续的多行 #，遵循 PEP 8 规范，每个 # 后面空一格。
三引号专司文档字符串：三引号在语法上是字符串字面量，其正统用途是位于模块、类或函数定义下方的文档字符串（Docstrings），受缩进与转义语法约束，不建议作为通用代码注释使用。