P1J-Python注释-什么是注释？为什么大厂程序员都在写文档字符串？怎么快速掌握注释规范？

P1J-Python注释-什么是注释？为什么大厂程序员都在写文档字符串？怎么快速掌握注释规范？

📝 摘要

面向零基础，系统讲解 Python 三种注释方式：单行注释、多行注释、文档字符串（docstring）。通过生活化比喻与实战对比，掌握 PEP 8 和 PEP 257 注释规范，写出易读易维护的专业代码。

---

目录

• 1. 前置知识点
• 2. 快速上手（3 分钟）
• 3. 什么是注释（comment（注释））
• 4. 单行注释（single-line comment（单行注释））
  • 4.1 基本用法
  • 4.2 PEP 8 单行注释规范
  • 4.3 行内注释（inline comment（行内注释））
• 5. 多行注释（multi-line comment（多行注释））
  • 5.1 使用连续单行注释
  • 5.2 使用多行字符串
• 6. 文档字符串（docstring（文档字符串））
  • 6.1 什么是文档字符串
  • 6.2 模块级文档字符串
  • 6.3 函数级文档字符串
  • 6.4 类级文档字符串
  • 6.5 PEP 257 文档字符串规范
  • 6.6 文档字符串格式风格
• 7. 注释 vs 文档字符串对比
• 8. 不使用注释的问题
• 9. 注释最佳实践
• 10. 常见错误与对比修正
• 11. 选择建议与实践流程
• 12. 📚 参考资料与学习资源
• 13. 总结

---

1. 前置知识点

在深入学习 Python 注释之前，你需要了解以下基础概念：

• 字符串（string（字符串））：用于表示文本数据，可以用单引号、双引号或三引号创建
• 函数（function（函数））：一段可重复使用的代码块，print() 是 Python 内置函数（built-in function（内置函数））
• 模块（module（模块））：一个包含 Python 代码的文件，可以导入到其他程序中使用
• 类（class（类））：面向对象编程的基础，用于创建对象的蓝图（本概念在本文档后部有详细介绍）

---

💡 学习建议：如果你是零基础，建议先学习 Python 基础语法（变量、字符串、函数），再学习注释相关内容。

---

2. 快速上手（3 分钟）

🔥 Must（必做实践）｜依赖：任意 Python 3 版本

目的：用一个最小示例快速了解 Python 三种注释方式——

• 单行注释：使用 # 注释单行代码
• 多行注释：使用连续 # 或三引号注释多行
• 文档字符串：使用 """ 为函数、类、模块添加说明

# 单行注释：解释下一行代码的作用
name = "Python"  # 这是行内注释，说明变量含义

"""
多行注释示例：
可以写多行说明
适合详细解释代码逻辑
"""

def greet(name):
    """
    问候函数：向指定的人打招呼
    
    参数:
    name (str): 要问候的人的姓名
    
    返回:
    str: 问候语
    """
    return f"你好，{name}！"

# 调用函数
message = greet("世界")
print(message)  # 输出：你好，世界！

输出结果：

你好，世界！

注释的价值：让代码成为可读的文档

注释就像代码的 说明书，让其他人（包括未来的你）能够快速理解代码的意图和逻辑，而不需要逐行分析代码本身。好的注释能够让代码维护成本降低 50% 以上。

---

3. 什么是注释（comment（注释））？

在深入学习 Python 注释之前，让我们先理解 注释（comment（注释）） 的本质和重要性。

注释的定义

注释（comment（注释）） 是程序中用于解释代码功能、说明代码逻辑的文本，Python 解释器会忽略注释内容，不会执行。注释就像代码的 说明书 或 旁白，帮助开发者理解代码的意图。

注释的作用

注释就像程序的 翻译官，让你能够：

1. 解释代码意图：说明代码为什么要这样写，而不是代码在做什么（代码本身已经说明了）
2. 提高可读性：帮助其他开发者（包括未来的你）快速理解代码逻辑
3. 记录设计决策：解释为什么选择这种实现方式，而不是其他方式
4. 临时禁用代码：通过注释快速屏蔽某些代码，用于调试
5. 生成文档：文档字符串可以自动生成 API 文档

注释的重要性

想象一下，如果没有注释，阅读代码会是什么样子：

# 没有注释的代码（难以理解）
def f(x, y):
    if x > 0 and y > 0:
        return (x ** 2 + y ** 2) ** 0.5
    return 0

有了注释，代码意图一目了然：

# 有注释的代码（清晰易懂）
def calculate_distance(x, y):
    """
    计算原点到点 (x, y) 的欧氏距离
    
    参数:
    x (float): 点的 x 坐标
    y (float): 点的 y 坐标
    
    返回:
    float: 距离值，如果坐标不合法返回 0
    """
    # 使用勾股定理计算距离
    if x > 0 and y > 0:
        return (x ** 2 + y ** 2) ** 0.5
    return 0  # 非正数坐标返回 0

注释让代码成为可读的文档，大大提高了代码的可维护性和团队协作效率。

Python 注释的类型

Python 提供了三种主要的注释方式：

1. 单行注释（single-line comment（单行注释））：以 # 开头，用于简短说明
2. 多行注释（multi-line comment（多行注释））：使用连续 # 或多行字符串，用于详细说明
3. 文档字符串（docstring（文档字符串））：使用三引号 """，用于描述模块、类、函数，可自动生成文档

注释的核心原则

根据 PEP 8 规范，编写注释应遵循以下原则：

1. 注释应该说明"为什么"，而不是"是什么"：代码本身已经说明了做什么，注释应解释为什么要这样做
2. 注释要与代码同步更新：过时的注释比没有注释更糟糕
3. 注释要简洁明了：避免冗余和废话
4. 使用文档字符串描述公共接口：所有公共函数、类、模块都应编写文档字符串

---

4. 单行注释（single-line comment（单行注释））

🔥 Must（必做实践）｜依赖：任意 Python 版本

单行注释是 Python 中最常用的注释方式，以 # 开头，用于对代码进行简短说明。单行注释就像代码的 便签纸，可以随时贴在代码旁边，提醒你这段代码的作用。

4.1 基本用法

单行注释的基本语法：

# 这是单行注释
代码内容  # 这是行内注释

示例：使用单行注释解释代码功能

# 计算圆的面积
pi = 3.14159  # 圆周率的近似值
radius = 5  # 圆的半径
area = pi * radius ** 2  # 使用公式 πr² 计算面积
print(f"圆的面积是：{area}")  # 输出结果

输出结果：

圆的面积是：78.53975

单行注释的使用场景：

1. 解释代码功能：在代码上方说明这段代码的作用
2. 说明变量含义：解释变量的用途和取值范围
3. 记录算法思路：说明算法的实现逻辑
4. 临时禁用代码：通过注释快速屏蔽某些代码行

示例：使用单行注释临时禁用代码

# 调试时临时禁用某些代码
# print("调试信息")  # 已注释，不会执行
print("正常输出")  # 这行会执行

4.2 PEP 8 单行注释规范

根据 PEP 8 编码规范，单行注释应遵循以下规则：

1. 注释符号后要有空格：# 后应有一个空格，然后才是注释内容
2. 注释要与代码对齐：注释应与其描述的代码保持相同的缩进级别
3. 注释要简洁明了：避免过长的注释，一般不超过 72 个字符

✅ 正确的注释写法：

# 计算两个数的和
result = a + b

# 多行代码的注释应该与代码对齐
def calculate_sum(numbers):
    total = 0  # 初始化累加器
    for num in numbers:
        total += num  # 累加每个数字
    return total

❌ 错误的注释写法：

#计算两个数的和（缺少空格）
result = a + b

#注释没有与代码对齐（缩进错误）
    def calculate_sum(numbers):
        total = 0

4.3 行内注释（inline comment（行内注释））

行内注释是写在代码行末尾的注释，用于解释该行代码的特定部分。

行内注释的规范（根据 PEP 8）：

1. 至少间隔两个空格：代码与 # 之间至少要有两个空格
2. 简洁明了：行内注释应简短，避免过长影响代码阅读

示例：行内注释的正确用法

x = 1  # 初始化变量 x
x = x + 1  # 将 x 的值加 1
print(x)  # 输出 x 的值

# 复杂表达式的行内注释
result = (a ** 2 + b ** 2) ** 0.5  # 使用勾股定理计算距离

示例：行内注释 vs 块注释的选择

当注释内容较短时，使用行内注释；当需要详细说明时，使用块注释：

# 方法 1：使用行内注释（简短说明）
total = 0  # 累加器

# 方法 2：使用块注释（详细说明）
# 初始化累加器：用于存储所有数字的总和
# 从 0 开始，逐步累加每个元素
total = 0

行内注释的注意事项：

1. 不要过度使用：只有当注释能够显著提高代码可读性时才使用行内注释
2. 保持简洁：行内注释应该简短，避免超过 72 个字符
3. 避免重复：如果代码本身已经很清晰，不需要添加行内注释

---

5. 多行注释（multi-line comment（多行注释））

⭐ Should（建议实践）｜依赖：任意 Python 版本

Python 没有专门的多行注释语法，但可以通过两种方式实现多行注释：连续的单行注释或多行字符串。多行注释就像代码的 详细说明书，用于解释复杂的算法逻辑或代码块的整体功能。

5.1 使用连续单行注释

使用连续的单行注释（每行以 # 开头）是实现多行注释的推荐方式，符合 PEP 8 规范。

示例：使用连续单行注释

# 这是一个多行注释的示例
# 用于详细说明代码的功能和逻辑
# 每行都以 # 开头，符合 PEP 8 规范
def calculate_fibonacci(n):
    # 计算斐波那契数列的第 n 项
    # 使用动态规划方法，避免递归的重复计算
    if n <= 1:
        return n
    a, b = 0, 1
    for i in range(2, n + 1):
        a, b = b, a + b
    return b

连续单行注释的优势：

1. 符合 PEP 8 规范：Python 官方推荐的注释方式
2. 清晰明确：每行都是注释，不会与代码混淆
3. 易于维护：可以逐行修改，不影响代码逻辑

5.2 使用多行字符串

使用三引号（""" 或 '''）创建的多行字符串也可以作为多行注释，但需要注意：这实际上是字符串对象，不是真正的注释。

示例：使用多行字符串作为注释

"""
这是一个多行字符串注释的示例
通常用于文件开头的模块说明
或用于临时禁用大段代码
"""
def calculate_area(radius):
    """计算圆的面积"""
    return 3.14159 * radius ** 2

⚠️ 注意事项：

1. 不是真正的注释：多行字符串会被 Python 解释器解析为字符串对象（虽然不会被使用）
2. 可能影响性能：在函数内部使用多行字符串作为注释，会在每次函数调用时创建字符串对象
3. 推荐用法：主要用于模块级文档字符串或临时禁用代码块

示例：多行字符串 vs 连续单行注释对比

# ✅ 推荐：使用连续单行注释（符合 PEP 8）
# 这是一个算法说明
# 详细解释了实现思路
# 每行都是注释，不会被解析
def algorithm():
    pass

# ❌ 不推荐：在函数内部使用多行字符串作为注释
def algorithm():
    """
    这不是注释，而是字符串对象
    每次函数调用都会创建这个字符串
    """
    pass

# ✅ 推荐：模块级使用多行字符串（用于文档字符串）
"""
模块说明：这是整个模块的文档字符串
可以包含模块的功能、作者、版本等信息
"""

---

6. 文档字符串（docstring（文档字符串））

🔥 Must（必做实践）｜依赖：任意 Python 版本

文档字符串（docstring（文档字符串））是 Python 中用于描述模块、类、函数的特殊字符串，位于定义的第一行。文档字符串就像代码的 产品说明书，不仅可以帮助开发者理解代码，还能自动生成 API 文档。大厂程序员都在使用文档字符串，因为它是 Python 官方推荐的代码文档化方式。

6.1 什么是文档字符串

文档字符串（docstring（文档字符串）） 是用于描述模块、类、函数或方法的字符串，使用三重引号（""" 或 '''）包围，位于定义的第一行。文档字符串会被 Python 解释器存储在对象的 __doc__ 属性中，可以通过 help() 函数或自动文档工具访问。

文档字符串的特点：

1. 位于定义的第一行：紧跟在 def、class、module 之后
2. 使用三引号：通常使用 """（符合 PEP 257 规范）
3. 可以被访问：通过 help() 函数或对象的 __doc__ 属性访问
4. 可以自动生成文档：工具如 Sphinx、pydoc 可以自动提取文档字符串生成文档

示例：文档字符串的基本结构

def add(a, b):
    """
    计算两个数的和
    
    这是一个简单的加法函数，用于演示文档字符串的基本用法。
    
    参数:
    a (int): 第一个加数
    b (int): 第二个加数
    
    返回:
    int: 两数之和
    
    示例:
    >>> add(2, 3)
    5
    """
    return a + b

# 访问文档字符串
print(add.__doc__)
help(add)

输出结果：

    计算两个数的和
    
    这是一个简单的加法函数，用于演示文档字符串的基本用法。
    
    参数:
    a (int): 第一个加数
    b (int): 第二个加数
    
    返回:
    int: 两数之和
    
    示例:
    >>> add(2, 3)
    5

Help on function add in module __main__:

add(a, b)
    计算两个数的和
    
    这是一个简单的加法函数，用于演示文档字符串的基本用法。
    
    参数:
    a (int): 第一个加数
    b (int): 第二个加数
    
    返回:
    int: 两数之和
    
    示例:
    >>> add(2, 3)
    5

6.2 模块级文档字符串

模块级文档字符串位于 Python 文件的最开始（在所有 import 语句之前），用于描述整个模块的功能、作者、版本等信息。

示例：模块级文档字符串

"""
数学工具模块（math_utils.py）

这个模块提供了常用的数学计算函数，包括：
- 加法、减法、乘法、除法
- 幂运算、开方运算
- 三角函数计算

作者：郑恩赐
版本：1.0.0
创建日期：2025-11-02
"""

import math

def add(a, b):
    """计算两个数的和"""
    return a + b

模块级文档字符串的结构（推荐）：

1. 第一行：模块的简要描述（一句话）
2. 空行
3. 详细描述：模块的功能、主要特性
4. 可选信息：作者、版本、创建日期等

6.3 函数级文档字符串

函数级文档字符串位于函数定义的下一行，用于描述函数的功能、参数、返回值等信息。

函数文档字符串的标准结构（根据 PEP 257）：

def function_name(param1, param2):
    """
    函数的简要描述（一句话）
    
    函数的详细描述，可以包含多行。
    说明函数的作用、使用场景等。
    
    参数:
    param1 (类型): 参数 1 的说明
    param2 (类型): 参数 2 的说明
    
    返回:
    类型: 返回值的说明
    
    异常:
    ValueError: 当参数不合法时抛出
    
    示例:
    >>> function_name(1, 2)
    结果示例
    """
    pass

示例：完整的函数文档字符串

def calculate_bmi(weight, height):
    """
    计算身体质量指数（BMI）
    
    使用公式 BMI = weight / (height ** 2) 计算 BMI 值。
    BMI 是衡量人体胖瘦程度的常用指标。
    
    参数:
    weight (float): 体重，单位：千克（kg）
    height (float): 身高，单位：米（m）
    
    返回:
    float: BMI 值，保留两位小数
    
    异常:
    ValueError: 当 weight 或 height 小于等于 0 时抛出
    
    示例:
    >>> calculate_bmi(70, 1.75)
    22.86
    >>> calculate_bmi(65, 1.68)
    23.03
    """
    if weight <= 0 or height <= 0:
        raise ValueError("体重和身高必须大于 0")
    bmi = weight / (height ** 2)
    return round(bmi, 2)

6.4 类级文档字符串

类级文档字符串位于类定义的下一行，用于描述类的功能、属性和方法等信息。

类文档字符串的标准结构：

class ClassName:
    """
    类的简要描述（一句话）
    
    类的详细描述，说明类的用途、主要功能等。
    
    属性:
    attr1 (类型): 属性 1 的说明
    attr2 (类型): 属性 2 的说明
    
    方法:
    method1(): 方法 1 的说明
    method2(): 方法 2 的说明
    
    示例:
    >>> obj = ClassName()
    >>> obj.method1()
    """
    pass

示例：完整的类文档字符串

class Student:
    """
    学生类
    
    用于表示一个学生的信息，包括姓名、年龄、成绩等。
    提供了获取和修改学生信息的方法。
    
    属性:
    name (str): 学生姓名
    age (int): 学生年龄
    scores (list): 学生成绩列表
    
    方法:
    get_average(): 计算平均分
    add_score(score): 添加新成绩
    
    示例:
    >>> student = Student("张三", 18)
    >>> student.add_score(90)
    >>> student.add_score(85)
    >>> student.get_average()
    87.5
    """
    
    def __init__(self, name, age):
        """初始化学生对象"""
        self.name = name
        self.age = age
        self.scores = []
    
    def get_average(self):
        """计算平均分"""
        if not self.scores:
            return 0
        return sum(self.scores) / len(self.scores)
    
    def add_score(self, score):
        """添加新成绩"""
        self.scores.append(score)

6.5 PEP 257 文档字符串规范

PEP 257 是 Python 文档字符串的官方规范，主要包含以下要点：

1. 使用三重双引号：推荐使用 """ 而不是 '''
2. 第一行是简要描述：应该是一句话，以句号结尾
3. 多行文档字符串：如果有多行，第一行后应该有空行
4. 为所有公共接口编写文档字符串：公共模块、函数、类、方法都应该有文档字符串
5. 文档字符串是语句：应该使用 """ 而不是赋值语句

✅ 正确的文档字符串（符合 PEP 257）：

def function():
    """简要描述函数功能。"""
    pass

def function():
    """
    简要描述函数功能。
    
    详细描述可以包含多行。
    说明函数的用途、参数、返回值等。
    """
    pass

❌ 错误的文档字符串（不符合 PEP 257）：

def function():
    """简要描述函数功能"""  # 缺少句号
    pass

def function():
    """简要描述函数功能。
    详细描述没有空行分隔"""  # 缺少空行
    pass

docstring = """文档字符串不能这样写"""  # 应该是语句，不是赋值

6.6 文档字符串格式风格

Python 社区有多种文档字符串格式风格，常用的有以下几种：

1. Google 风格：简洁明了，易于阅读
2. NumPy 风格：详细规范，适合科学计算
3. reStructuredText 风格：功能强大，适合复杂文档

Google 风格示例（推荐初学者使用）：

def calculate_area(radius):
    """
    计算圆的面积
    
    Args:
        radius (float): 圆的半径
        
    Returns:
        float: 圆的面积
        
    Raises:
        ValueError: 当 radius 小于等于 0 时
        
    Example:
        >>> calculate_area(5)
        78.54
    """
    if radius <= 0:
        raise ValueError("半径必须大于 0")
    return 3.14159 * radius ** 2

NumPy 风格示例（适合科学计算）：

def calculate_area(radius):
    """
    计算圆的面积
    
    Parameters
    ----------
    radius : float
        圆的半径
        
    Returns
    -------
    float
        圆的面积
        
    Raises
    ------
    ValueError
        当 radius 小于等于 0 时
        
    Examples
    --------
    >>> calculate_area(5)
    78.54
    """
    if radius <= 0:
        raise ValueError("半径必须大于 0")
    return 3.14159 * radius ** 2

选择建议：

• 初学者：使用 Google 风格，简洁易懂
• 科学计算项目：使用 NumPy 风格，规范详细
• 大型项目：使用 reStructuredText 风格，功能强大

---

7. 注释 vs 文档字符串对比

注释和文档字符串虽然都是用于说明代码，但它们的用途和使用场景不同：

特性	注释（Comment）	文档字符串（Docstring）
语法	# 开头	三引号 """ 包围
位置	代码任意位置	定义的第一行
用途	解释代码逻辑、算法思路	描述函数、类、模块的功能
可访问性	不可通过代码访问	可通过 help() 和 __doc__ 访问
文档生成	不能自动生成文档	可以自动生成 API 文档
适用场景	代码内部说明、临时禁用	公共接口的官方文档

使用建议：

• 使用注释：解释复杂的算法、记录设计决策、临时禁用代码
• 使用文档字符串：为所有公共函数、类、模块编写官方文档

---

8. 不使用注释的问题

对比示例：不使用注释 vs 使用注释

❌ 不使用注释的代码（难以理解和维护）

def f(x, y):
    if x > 0 and y > 0:
        return (x ** 2 + y ** 2) ** 0.5
    return 0

def process_data(data):
    result = []
    for item in data:
        if item and isinstance(item, dict):
            temp = {}
            for k, v in item.items():
                if k and v:
                    temp[k.upper()] = str(v).strip()
            if temp:
                result.append(temp)
    return result

问题分析：

1. 函数意图不明确：f() 做什么？process_data() 处理什么数据？
2. 参数含义不清：x、y 代表什么？data 是什么格式？
3. 返回值不明：返回值的含义是什么？
4. 维护困难：3 个月后，你可能都忘了这些函数是干什么的

✅ 使用注释和文档字符串的代码（清晰易懂）

def calculate_distance(x, y):
    """
    计算原点到点 (x, y) 的欧氏距离
    
    使用勾股定理计算两点之间的距离。
    
    参数:
    x (float): 点的 x 坐标
    y (float): 点的 y 坐标
    
    返回:
    float: 距离值，如果坐标不合法返回 0
    
    示例:
    >>> calculate_distance(3, 4)
    5.0
    """
    # 验证坐标合法性：必须为正数
    if x > 0 and y > 0:
        # 使用勾股定理：√(x² + y²)
        return (x ** 2 + y ** 2) ** 0.5
    return 0  # 非正数坐标返回 0


def process_user_data(data):
    """
    处理用户数据列表，转换为标准格式
    
    将用户数据字典列表进行清洗和格式化：
    - 过滤空数据
    - 将键转换为大写
    - 将值转换为字符串并去除空白
    
    参数:
    data (list): 用户数据列表，每个元素是字典
    
    返回:
    list: 处理后的用户数据列表
    
    示例:
    >>> data = [{"name": " 张三 ", "age": 25}, {"name": "李四"}]
    >>> process_user_data(data)
    [{'NAME': '张三', 'AGE': '25'}]
    """
    result = []
    # 遍历每个用户数据项
    for item in data:
        # 验证数据有效性：非空且为字典类型
        if item and isinstance(item, dict):
            temp = {}
            # 处理每个键值对
            for k, v in item.items():
                # 过滤空键和空值
                if k and v:
                    # 键转大写，值转字符串并去除空白
                    temp[k.upper()] = str(v).strip()
            # 只添加非空字典
            if temp:
                result.append(temp)
    return result

对比结果：

• 可读性提升 90%：代码意图一目了然
• 维护成本降低 70%：3 个月后仍能快速理解
• 团队协作效率提升：其他开发者无需猜测代码意图
• 错误率降低：清晰的注释减少理解错误

---

9. 注释最佳实践

根据 PEP 8 和 PEP 257 规范，以下是注释的最佳实践：

9.1 注释的“为什么”原则

❌ 错误：注释说明"是什么"（代码已经说明了）

# 将 x 加 1
x = x + 1

# 计算两个数的和
result = a + b

✅ 正确：注释说明"为什么"（解释设计决策）

# 计数器加 1，用于循环控制
x = x + 1

# 使用内置 sum 而不是循环，提高性能
result = sum([a, b])

9.2 保持注释与代码同步

❌ 错误：过时的注释（比没有注释更糟糕）

# 计算两个数的和
result = a * b  # 代码已经改成乘法，注释还是加法

✅ 正确：及时更新注释

# 计算两个数的乘积（修改于 2025-11-02）
result = a * b

9.3 简洁明了的注释

❌ 错误：冗余的注释

# 这是一个变量
name = "Python"

# 定义一个函数，函数名为 greet，参数为 name
def greet(name):
    # 返回一个字符串
    return f"Hello, {name}"

✅ 正确：简洁有用的注释

name = "Python"  # 编程语言名称

def greet(name):
    """向指定的人打招呼"""
    return f"Hello, {name}"

9.4 为公共接口编写文档字符串

✅ 推荐做法：

"""
用户管理模块

提供用户创建、查询、更新等功能。
"""

def create_user(name, email):
    """
    创建新用户
    
    参数:
    name (str): 用户姓名
    email (str): 用户邮箱
    
    返回:
    dict: 创建的用户信息
    """
    pass

def _validate_email(email):  # 私有函数，使用单行注释即可
    """验证邮箱格式（内部函数）"""
    pass

9.5 注释格式规范

1. 注释符号后要有空格：# 注释 而不是 #注释
2. 注释要与代码对齐：保持相同的缩进级别
3. 行内注释至少间隔两个空格：code # 注释
4. 注释长度不超过 72 个字符：确保在不同屏幕上都能完整显示

---

10. 常见错误与对比修正

10.1 错误：注释缺少空格

❌ 错误写法：

#这是注释（缺少空格）
x = 1  #这也是注释（缺少空格）

✅ 正确写法：

# 这是注释（有空格）
x = 1  # 这也是注释（有空格）

10.2 错误：注释与代码不对齐

❌ 错误写法：

def function():
# 注释没有对齐
    x = 1

✅ 正确写法：

def function():
    # 注释与代码对齐
    x = 1

10.3 错误：文档字符串位置错误

❌ 错误写法：

def function():
    x = 1
    """
    文档字符串不能在函数中间
    """

✅ 正确写法：

def function():
    """
    文档字符串必须在函数定义的第一行
    """
    x = 1

10.4 错误：过度注释

❌ 错误写法：

# 定义一个变量 name
name = "Python"  # 变量 name 的值是 "Python"
# 打印变量 name
print(name)  # 打印 name 的值

✅ 正确写法：

name = "Python"
print(name)  # 代码本身已经很清晰，不需要注释

10.5 错误：注释与代码不一致

❌ 错误写法：

# 计算两个数的和
result = a * b  # 注释说的是加法，代码是乘法

✅ 正确写法：

# 计算两个数的乘积
result = a * b

---

11. 选择建议与实践流程

11.1 注释类型选择指南

何时使用单行注释：

• 解释单行代码的功能
• 说明变量的含义
• 临时禁用代码
• 记录算法思路

何时使用多行注释：

• 解释复杂算法逻辑
• 说明代码块的总体功能
• 记录设计决策

何时使用文档字符串：

• 为所有公共函数编写文档
• 为所有公共类编写文档
• 为模块编写说明文档
• 需要自动生成 API 文档时

11.2 学习路径建议

初学者（零基础）：

1. ✅ Must（必做实践）：掌握单行注释的基本用法
2. ✅ Must（必做实践）：为所有函数编写简单的文档字符串
3. ⭐ Should（建议实践）：学习 PEP 8 注释规范

进阶学习者（有基础）：

1. ✅ Must（必做实践）：掌握完整的文档字符串格式
2. ⭐ Should（建议实践）：学习 Google 或 NumPy 风格的文档字符串
3. 💡 Could（可选实践）：使用 Sphinx 自动生成文档

11.3 实践项目建议

项目 1：为现有代码添加注释

# 选择一个你之前写的 Python 程序
# 为所有函数添加文档字符串
# 为复杂逻辑添加注释
# 检查是否符合 PEP 8 规范

项目 2：创建带完整文档的模块

"""
创建一个数学工具模块
- 为模块编写模块级文档字符串
- 为每个函数编写完整的文档字符串
- 使用 Google 风格格式
- 包含参数、返回值、示例等信息
"""

11.4 最佳实践检查清单

在编写代码时，检查以下清单：

• 所有公共函数都有文档字符串
• 所有公共类都有文档字符串
• 复杂算法有注释说明
• 注释说明了"为什么"而不是"是什么"
• 注释与代码保持同步
• 注释格式符合 PEP 8 规范
• 文档字符串符合 PEP 257 规范

---

12. 📚 参考资料与学习资源

官方文档

• PEP 8 - Python 编码风格指南：pep8.org/
• PEP 257 - 文档字符串约定：www.python.org/dev/peps/pe…
• Python 官方文档 - 文档字符串：docs.python.org/zh-cn/3/tut…

在线教程

• Real Python - Python 注释指南：realpython.com/python-comm…
• Google Python 风格指南：google.github.io/styleguide/…
• NumPy 文档字符串指南：numpydoc.readthedocs.io/

工具推荐

• pydoc：Python 自带的文档生成工具
• Sphinx：功能强大的文档生成工具，支持多种格式
• docstring-generator：自动生成文档字符串的 IDE 插件

推荐书籍

• 《Python 编程：从入门到实践》- Eric Matthes
• 《编写高质量 Python 代码的 59 个有效方法》- Brett Slatkin

---

13. 总结

通过本文档的学习，你已经掌握了 Python 注释的核心技能：

核心要点回顾

1. 三种注释方式：

   • 单行注释（#）：用于简短说明
   • 多行注释（连续 #）：用于详细说明
   • 文档字符串（"""）：用于官方文档

2. 注释的核心原则：

   • 说明"为什么"，而不是"是什么"
   • 保持注释与代码同步
   • 简洁明了，避免冗余

3. 文档字符串的重要性：

   • 大厂程序员都在使用文档字符串，因为它是 Python 官方推荐的代码文档化方式
   • 可以为代码自动生成 API 文档
   • 提高代码的可维护性和团队协作效率

学习建议

注释和文档字符串是编写专业 Python 代码的必备技能。建议你：

1. 立即开始实践：为你现有的代码添加注释和文档字符串
2. 遵循 PEP 规范：按照 PEP 8 和 PEP 257 规范编写注释
3. 养成良好习惯：编写代码的同时就写好注释，而不是事后补充

下一步学习

掌握了注释之后，建议继续学习：

• P2A：列表 List - Python 最常用的数据结构
• P3A：函数定义和调用 - 深入学习函数的用法
• 代码风格规范 - 进一步提升代码质量

记住：好的代码应该是自解释的，但当代码本身无法完全表达意图时，注释和文档字符串就是最好的补充。编写清晰、规范的注释，不仅是对自己负责，也是对团队负责。继续加油，你正在成为一名专业的 Python 开发者！

---

厦门工学院人工智能创作坊 -- 郑恩赐
2025 年 11 月 02 日