Python基础：注释的写法（单行、多行、文档注释）

在上一章，我们系统学习了Python输入input与输出print函数，掌握了程序与用户交互的核心方法。本章我们将学习Python编程的基础必备知识点------注释写法。注释是代码的灵魂，是新手入门必须养成的编码习惯，也是企业项目开发的硬性规范，对代码可读性、后期维护、团队协作至关重要。

一、核心概念与背景

1.1 什么是Python注释

基本定义：

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_avg(num_list):
    """
    计算数字列表的平均值
    Args:
        num_list (list): 传入数字列表
    Returns:
        float: 返回列表平均值，空列表返回0
    """
    if not num_list:
        return 0
    return sum(num_list) / len(num_list)

# 调用测试
print(calculate_avg([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)

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

日常编码中，手动逐行写注释效率极低，主流编辑器均支持注释快捷键，新手必掌握！

编辑器	注释快捷键	功能说明
PyCharm	Ctrl + /	选中代码一键批量单行注释/取消注释
VS Code	Ctrl + /	批量单行注释，Shift+Alt+A 多行注释
IDLE	Alt + 3/4	Alt+3注释，Alt+4取消注释

四、常见问题与避坑方案

4.1 注释嵌套报错

问题现象：三引号注释内部嵌套三引号，程序报错

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

解决方案：注释内部避免嵌套同类型三引号，或使用转义符，优先统一注释格式

4.2 注释冗余、过度注释

问题现象：简单代码堆砌大量无用注释，代码臃肿

错误写法：

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

解决方案：简单代码不注释，复杂逻辑、核心算法、业务逻辑重点注释

4.3 行尾注释间距不规范

问题现象：代码和注释无间距，可读性差，不符合PEP8规范

规范：行尾注释与代码之间空两个空格，再写#注释

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

5.1 注释书写规范

• 单行注释：# 后面必须加一个空格，再书写注释内容

• 独立行注释：用于解释下一行/下一段代码，禁止无意义空注释

• 文档注释：函数、类、模块必须标配，参数、返回值描述清晰

• 注释语言统一：项目中统一中文或英文，不要混合使用

5.2 注释使用原则

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

5.3 安全与开发小贴士

• 禁止在注释中记录密码、密钥、接口token等敏感信息

• 迭代代码时同步更新注释，避免注释与代码逻辑不符

• 删除废弃代码，不要单纯注释留存，避免项目冗余

六、本章小结

6.1 核心要点回顾

• 单行注释：# 开头，适用于单行简单说明、行尾备注

• 多行注释：三引号实现，适用于大段说明、批量屏蔽代码

• 文档注释：标准化注释，适配函数、类、模块，企业开发必备

• 掌握编辑器快捷键，遵循PEP8注释规范，规避常见注释误区

6.2 实践学习建议

学习阶段	建议内容	时间安排
入门	熟练掌握三种注释写法，规范练习注释排版	1天
进阶	给之前写的print、变量代码补充规范注释	1天
高级	熟练书写函数、类标准文档注释，适配项目开发	2天