Python中文档字符串是个啥？

2026-08-27 Python,文档字符串

Python中"""是个啥？

很多初学者（甚至部分教程）会用 """ 来“注释”掉大段代码，但在 Python 的底层语法定义中，""" 不是注释符，它是一个字符串字面量（String Literal）的定界符，通常被称为文档字符串（Docstring）。

Python 中真正的注释符只有一个，就是 #。

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

当你写下下面这段代码时，它确实“没报错”且“被忽略了”：

"""
这是一大段文字
可以换行
看起来像被注释掉了
"""
print("Hello")

底层原理：Python 解释器在运行时，会创建一个包含这三行文字的字符串对象。但由于这个字符串没有被赋值给任何变量，也没有被任何表达式使用，它会被 Python 的垃圾回收机制立刻销毁。因为这个过程不影响程序逻辑，所以给人一种“被注释掉”的错觉。

但是，它和真正的注释 # 有本质区别：

对比项 # 真正的注释 """ 三引号字符串
语法性质 预处理器指令，解释器完全忽略，不生成任何代码。 合法的 Python 字符串表达式，会生成字符串对象（即使立即被销毁）。
内存占用 0 字节，完全不占用运行时内存。 会短暂分配内存，频繁使用会有微小性能开销。
缩进敏感 从 # 开始到行尾，不受缩进影响。 受缩进影响！ 如果缩进不对，会报语法错误。

2. """ 的真正用途：文档字符串（Docstring）

在企业级开发中，""" 唯一且正确的核心用途是写在函数、类、模块的开头，作为官方的文档说明。

这个字符串会被 Python 解释器“记住”，并绑定到对象的 .__doc__ 属性上，供 IDE 提示和 help() 函数调用。

def calculate_salary(base: float, bonus: float) -> float:
    """
    计算员工的最终薪资。

    参数:
        base (float): 底薪
        bonus (float): 奖金金额

    返回:
        float: 底薪与奖金之和
    """
    return base + bonus

# 企业级实践：可以通过 help() 查看规范文档
print(calculate_salary.__doc__)  # 这会打印出上面的文档字符串

3. 用 """ 做注释为什么不规范？

根据 PEP 8（Python 官方编码规范），""" 仅用于文档字符串。如果用它来注释大段废弃代码，会有两个问题：

  1. 缩进灾难：如果被“注释”的代码块缩进不同，Python 会抛出 IndentationError。

    def test():
    """
    这里没问题
    """
        """ 这里缩进多了一格，直接报错！ """  # 语法错误

  2. 混淆文档生成工具：像 Sphinx 这类自动生成 API 文档的工具，会解析文件中第一个 """ 作为模块文档，如果用它注释代码，会导致生成的文档变成垃圾内容。

4. 企业级最佳实践

  • 注释代码：永远使用 #。多行注释可以每行开头加一个 #。

    # 这是一个多行注释
# 这是第二行
# 这是第三行

  • 写文档/说明：永远使用 """ 放在函数/类的第一行。这是 Python 官方钦定的写法，IDE 会自动识别并弹出智能提示。

  • IDE 快捷键：在 PyCharm 或 VSCode 中，选中多行代码后按 Ctrl + /（Windows）或 Cmd + /（Mac），编辑器会自动帮你加上 # 注释，不会用 """。

一句话总结：# 是“解释给自己和同事看的备注”，""" 是“写给程序和使用者看的说明书”。千万别把 """ 当成注释来用，这在代码 Review 时会被资深工程师打回重写。