Python基础之注释的三种写法(单行、多行、文档注释)详解

在上一章，我们系统学习了Python的输入输出函数，掌握了程序与用户交互的基本方法。这一章我们来聊聊一个看似简单、但实际非常关键的基础技能——注释。

说白了，注释就是写给开发者自己看的“代码说明书”。对于刚入门的新手来说，养成规范的注释习惯，甚至比学会某个特定语法更重要。为什么？因为代码是写给人看的，机器只是顺带执行一下。一个没有注释的代码文件，就像一个没有说明书的复杂机械，过两周你自己都可能看不懂。

一、核心概念与背景

1.1 什么是Python注释

解释器在运行代码时，会完全忽略掉注释内容。换句话说，注释的存在不会对程序的执行结果产生任何影响。它们的唯一目的，就是辅助开发者理解代码逻辑。

简单总结：注释是写给人看的，代码是写给机器跑的。

# 注释演示示例
​​​​​​​print("代码会执行") # 本行注释不会执行，仅做说明

1.2 注释的核心作用

很多新手觉得写注释是浪费时间，但真正经历过大型项目开发的人都知道，规范的注释在关键时刻能救命。它的核心价值主要体现在这几个方面：

• 提升可读性：快速看懂代码逻辑、功能用途，避免自己写的代码隔天就忘了是什么意思。
• 方便后期维护：项目迭代、bug修复时，清晰注释能大幅降低理解成本。
• 助力团队协作：团队开发中，好的注释能让同事快速读懂你的代码，协作效率翻倍。
• 辅助代码调试：临时注释掉某些代码段来排查问题，是调试过程中最常用的技巧之一。

1.3 注释典型应用场景

二、Python三大注释详解

2.1 单行注释（最常用）

单行注释是Python中最简单、最常用的注释方式。它的语法很直观：以# 符号开头，从#开始到本行末尾的所有内容，都会被解释器忽略。

语法格式：# 注释内容

来看一个具体的代码示例：

# 单行注释：定义用户姓名
username = "Python学习者"

# 单行注释：定义用户年龄
age = 25

# 输出用户信息
print(f"用户：{username}，年龄：{age}")  # 行尾注释：打印基础用户信息

这种注释方式的核心特点很明确：

• 仅作用于当前行，简洁灵活
• 可以单独成行，也可以放在代码行的末尾
• 适合标注简单逻辑、单行代码的功能说明

2.2 多行注释（批量注释）

当需要注释的内容比较多，比如一大段逻辑说明，或者想临时屏蔽掉一大段代码，单行注释就显得力不从心了。这时候，多行注释就派上了用场。

Python本身没有专门的多行注释语法，通常是通过三引号（单引号或双引号均可）来实现的。

语法格式：

'''多行注释内容 多行注释内容 '''

或

"""多行注释内容 多行注释内容 """

代码示例：

'''
多行注释演示
功能：计算两个数字的和
作者：Python学习者
时间：2026-05-30
'''
def add_num(a, b):
    return a + b

"""
双三引号多行注释
可用于批量屏蔽测试代码
print("测试代码1")
print("测试代码2")
"""
print(add_num(10, 20))

它的特点很明显：

• 支持任意行数的文本注释，不需要逐行加#
• 单三引号和双三引号功能完全一致，随意使用即可
• 适合大段说明、代码批量屏蔽的场景

2.3 文档注释（项目必备）

文档注释是一种规范化的多行注释，专门用来描述函数、类或模块的功能、参数、返回值和使用方法。在企业级开发中，这几乎是硬性要求。而且很多自动化文档生成工具都能直接识别并提取文档注释，生成项目文档。

使用规范很严格：必须放在函数、类、模块的第一行，并且使用双三引号包裹。

先看一个基础示例——模块注释：

"""
项目模块：基础计算模块
功能：实现加减乘除基础运算
作者：Python学习者
版本：1.0
更新时间：2026-05-30
"""

print("基础计算模块加载完成")

再来看一个进阶示例——函数文档注释，这是标准的企业写法：

def calculate_a vg(num_list):
    """
    计算数字列表的平均值
    Args:
        num_list (list): 传入数字列表
    Returns:
        float: 返回列表平均值，空列表返回0
    """
    if not num_list:
        return 0
    return sum(num_list) / len(num_list)

# 调用测试
print(calculate_a vg([85, 90, 88]))

最后是一个高阶示例——类文档注释：

class Student:
    """
    学生信息管理类
    实现学生成绩添加、平均分计算功能
    """
    def __init__(self, name, age):
        """
        初始化学生信息
        Args:
            name (str): 学生姓名
            age (int): 学生年龄
        """
        self.name = name
        self.age = age
        self.grades = []

    def add_grade(self, grade):
        """添加学生成绩"""
        self.grades.append(grade)

三、实操快捷键（提升编码效率）

在日常编码中，每行都手动输入#显然太慢了。主流编辑器都提供了注释快捷键，新手务必掌握这个效率工具。

四、常见问题与避坑方案

4.1 注释嵌套报错

有时候会遇到这样的问题：在三引号注释内部又嵌套了三引号，程序直接报错。

"""
外层注释
""" 内层嵌套三引号 """
"""

解决方案其实很简单：注释内部避免嵌套同类型的引号，或者使用转义符。最稳妥的做法是统一注释格式，不要混用。

4.2 注释冗余、过度注释

还有一种常见问题是“过度注释”——明明是一行非常简单的代码，非要堆砌一堆解释，反而让代码变得臃肿。

错误写法示例：

# 定义a变量，赋值为10
a = 10
# 打印a变量
print(a)

正确的做法是：简单代码不注释，复杂逻辑、核心算法、业务功能才需要重点注释。注释的目的是帮助理解，而不是把代码翻译成中文。

4.3 行尾注释间距不规范

行尾注释如果紧贴着代码，可读性会很差，而且不符合PEP8编码规范。正确的做法是：代码与注释之间至少空两个空格，再写#号开始注释。

五、官方编码最佳实践（PEP8规范）

5.1 注释书写规范

• 单行注释：# 后面必须加一个空格，再书写注释内容。
• 独立行注释：用于解释下一行或下一段代码，禁止写无意义的空注释。
• 文档注释：函数、类、模块必须标配，参数、返回值描述要清晰。
• 注释语言统一：项目里要么全部用中文，要么全部用英文，不要混用。

5.2 注释使用原则

记住两句核心口诀：简单代码不注释，复杂逻辑详注释；业务功能必注释，冗余代码不瞎注。

5.3 安全与开发小贴士

• 绝对不要在注释中记录密码、密钥、接口token等敏感信息，这是安全底线。
• 迭代代码时同步更新注释，避免注释与代码逻辑不一致，反而造成误导。
• 废弃代码直接删掉，不要单纯注释留存，以免项目变得冗余混乱。

六、本章小结

核心要点回顾

• 单行注释：# 开头，适用于单行简单说明、行尾备注。
• 多行注释：三引号实现，适用于大段说明、批量屏蔽代码。
• 文档注释：标准化注释，适配函数、类、模块，企业开发必备。
• 掌握编辑器快捷键，遵循PEP8注释规范，规避常见的注释误区。