Python单行注释与多行注释怎么写

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

单行注释是 Python 中最常见、最基础的注释形式。它的基本语法非常简单：在一行的任意位置输入井号 #，从 # 开始到该行末尾的所有字符都会被解释器视为注释，不参与编译与执行。

1. 独立单行注释（代码块注释）

独立单行注释单独占据一行代码空间，通常放置在要说明的代码语句或函数的前上方。根据官方代码风格规范 PEP 8，书写独立单行注释时需遵循两个排版细节：

• 保留半角空格：井号 # 与随后的第一位注释汉字或英文之间，必须保留一个空格，避免字符紧贴导致视觉拥挤。
• 对齐层级缩进：注释行必须与下方紧随的代码保持完全相同的缩进空格数（如4个空格），绝不能顶格书写或过度缩进。

# 正确示例：井号后留空格，且缩进与紧随的代码保持一致
def calculate_shipping(weight, distance):
    # 基础运费按首重 10 元计算
    base_fee = 10.0
    
    # 超过 5 公斤的部分按每公斤 2 元加收超重费
    if weight > 5.0:
        base_fee += (weight - 5.0) * 2.0
        
    return base_fee

2. 行尾内联注释（Inline Comments）

行尾注释位于可执行代码语句的同一行后方，用于对该行的某个特定常量、变量赋值或特殊边界进行补充说明。

PEP 8 对行尾注释有明确的排版间距约束：代码语句末尾与井号 # 之间必须保留至少两个空格；井号后同样空出一格再书写文字。这样能确保阅读代码逻辑时，代码本体与辅助说明之间有清晰的视觉分界。

# 行尾注释规范：代码结束与 # 之间保留 2 个空格
MAX_RETRIES = 3      # 网络请求失败后的最大重试次数
TIMEOUT_SECONDS = 5  # 单次 Socket 连接超时阈值（秒）

x = buffer_size - 1  # 预留末尾空字符位置

图 1：单行注释与行尾注释的编写规范与排版细节说明

二、Python多行注释怎么写

初学 Python 的读者常有一个疑问：Python 是否像 C、Java 那样拥有类似 /* ... */ 的专属多行注释符号？答案是没有。Python 语言语法设计中并没有专门的原生多行注释开闭符，但社区与官方形成了两种成熟的实践方式。

方法一：连续使用多个单行井号（PEP 8 官方推荐）

在 Python 官方指导规范 PEP 8（Style Guide for Python Code）中，明确推荐的多行“块注释（Block Comments）”做法是：每一行注释都以 # 开头并空一格，多行紧密连续排列。如果注释分为多个段落，段落之间用只包含单个 # 的空行隔开。

# 官方推荐的多行块注释写法
# 该段算法用于解析来自边缘节点的原始传感器数据包。
#
# 首先对前导校验和进行循环冗余校验（CRC32），
# 校验通过后再依据协议格式对浮点型温度、湿度序列
# 进行解包并压入消息队列中等待消费。
def process_sensor_packet(raw_data):
    pass

这种写法的好处在于：在词法分析阶段，每一行 # 都会被词法解析器（Lexer）当场直接剔除，完全不进入抽象语法树（AST），绝对不会对程序的运行时内存、作用域或执行速度带来任何附带影响。

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

Python 允许使用成对的三个单引号 ''' 或三个双引号 """ 来定义跨多行的字符串字面量。当一个三引号多行字符串没有赋值给任何变量、也没有参与函数调用时，Python 语法允许其作为独立的表达式语句存在。因此在日常编程中，很多人习惯用三引号来书写大段注释。

"""
这是一个通过双三引号实现的多行注释块。
在这里可以随意输入多行文字，
换行无需手动添加井号。
"""
def sync_user_status():
    '''
    在函数内部同样可以使用单三引号作为多行说明，
    但必须严格对齐当前函数的内部缩进。
    '''
    pass

图 2：连续井号（#）与三引号字符串在底层解析与运行时的行为差异对比

三、连续井号与三引号的本质差异与避坑

虽然连续井号和三引号都可以让人眼看到多行说明，但在 Python 编译器视角下，它们在底层机制上有本质区别。如果盲目把三引号当成通用注释，容易遇到隐蔽的语法报错。

1. 严格的缩进约束陷阱（IndentationError）

真正的注释符 # 是语法无关的辅助标记，即便写在行内任意位置，编译器也不会追究缩进严谨性。但三引号多行字符串是 Python 语法树中的一个真正的表达式语句。

这意味着：在带有缩进的代码块（如函数、类定义、if/for/while 代码块）内部，三引号字符串的起始符与结束符必须严格遵循当前代码块的缩进层级。如果把三引号顶格书写，Python 会直接报 IndentationError: unexpected indent 或语法中断。

# 常见错误示范：在函数内随意顶格书写三引号多行注释
def process_data(items):
    valid_count = 0
"""
这里如果顶格写三引号，Python 会直接抛出缩进错误！
IndentationError: unindent does not match any outer indentation level
"""
    for item in items:
        valid_count += 1
    return valid_count

2. 文档字符串（Docstring）与普通注释的区别

如果三引号多行字符串紧跟在模块顶部、类定义下方第一行、或函数定义下方第一行，它会被 Python 解释器特殊对待，自动作为该对象的 __doc__ 属性进行存储。

这类特殊的字符串被称为“文档字符串（Docstring）”，可以通过内置的 help() 函数查看，也是各大 IDE 提供智能补全、浮窗提示和 Sphinx 等工具自动生成 API 文档的数据来源。因此，三引号应当优先专用于编写模块与函数接口说明，而不是散落在代码行之间代替逻辑注释。

def get_active_users(days=30):
    """
    根据最近登录时间筛选活跃用户列表。

    参数:
        days (int): 统计判定的天数窗口，默认 30 天。

    返回:
        list[dict]: 包含用户ID和基础信息的字典列表。
    """
    # 这里是具体的实现逻辑，内部细节推荐用连续 # 进行注释
    query_threshold = get_current_time() - days * 86400
    return fetch_from_db(query_threshold)

# 可在终端或代码中直接读取该文档属性
print(get_active_users.__doc__)

图 3：根据使用场景选择正确的注释类型决策路径

四、编辑器快捷键批量生成多行注释

在实际开发过程中，面对数十行甚至成百上千行的复杂代码或临时测试片段，不需要一行一行手动敲入 # 符号。主流代码编辑器均内置了一键切换单行与多行注释的快捷键：

配合编辑器的快捷键，使用 PEP 8 推荐的“连续井号”写多行注释既能保证百分之百符合规范，又不会增加任何手工输入的负担。

五、编写高质量 Python 注释的核心准则与避坑清单

能正确敲出注释符号只是第一步，让注释真正发挥辅助团队协作、降低维护成本的作用，还需要遵循合理的工程习惯。

图 4：Python 注释四大黄金准则与避坑要点

1. 解释“为什么这样做（Why）”，而不是复述“做了什么（What）”： 良好的代码命名本身应该具备自解释能力。像 total = price * count # 用单价乘以数量 这样的注释毫无价值。注释的宝贵价值在于解释那些代码无法直接传达的信息，例如：为什么使用 0.85 换算率、为什么特定硬件协议需要延迟 200 毫秒、此处的边界值是为了规避什么旧版本漏洞。
2. 保持注释与代码严格同步： 代码逻辑变更后，如果对应的注释没有及时修改，就会形成“误导性注释”。过时、错误的注释比完全没有注释对维护者造成的干扰更大。在重构代码的同时，务必将关联的注释与文档字符串同步修正。
3. 避免用注释长期留存废弃代码（僵尸代码）： 有些开发者习惯把不再使用的算法代码用 # 注释掉保留在原处。现代软件工程中，历史版本回溯完全由 Git 等版本控制系统来管理，大量注释掉的代码只会破坏文件结构、干扰全局搜索。确认无用的逻辑应当直接删除。

六、总结速查

归纳起来，Python 注释的编写方式可以总结为以下三条实用结论：

• 单行说明：使用 #，独立成行对齐代码缩进，井号后空一格；行尾内联时与代码隔开两个空格。
• 多行内部逻辑或屏蔽代码：使用连续的 #（善用编辑器的 Ctrl + / 快捷键），这是 PEP 8 推荐的最佳实践，零开销且不受表达式语法陷阱干扰。
• 模块、类与函数的对外接口说明：必须使用成对的三引号文档字符串（Docstring），规范陈述功能、入参类型与返回值。