Python3 注释

Python3 注释

---

🎯 学习目标

掌握 Python 中

• 单行注释、
• 多行注释、
• 文档字符串

的使用方法，

理解其在代码可读性、团队协作和后期维护中的重要性，

并能在实际项目中灵活运用。

---

🔑 核心重点

分类	内容
单行注释	使用 # 开头的注释，用于解释一行代码
多行注释	使用三引号（''' 或 """）包裹的注释，适合长段说明
文档字符串	模块、类或函数开头的注释，用于生成 API 文档
注释规范	编码风格、团队约定、注释工具支持（如 Sphinx、PyCharm 提示）
实际应用场景	代码说明、调试标记、版本更新日志、功能说明等

---

📚 详细讲解

一、什么是注释？

注释是程序中不会被 Python 解释器执行的文本内容，主要用于：

• 解释代码逻辑
• 提醒开发者注意事项
• 辅助调试
• 生成文档

Python 支持三种注释方式：

1. 单行注释：以 # 开始
2. 多行注释：用三引号（''' 或 """）包围
3. 文档字符串（Docstring）：写在模块、类或函数定义的第一行，用于说明用途和参数信息

---

二、单行注释

✅ 基本语法：

# 这是一个单行注释
print("Hello, World!")

✅ 示例：

# 定义一个变量
name = "Alice"

# 打印欢迎信息
print(f"欢迎你，{name}！")

📌 特点：

• 只作用于当前行
• 简洁明了，适合解释某一行代码的作用
• 可放在代码行末

---

三、多行注释

✅ 基本语法：

使用三个单引号 ' 或双引号 " 包裹注释内容：

'''
这是一个
多行注释
'''
print("Hello, World!")

或

"""
这也是
多行注释
"""
print("Hello, World!")

✅ 示例：

'''
这是一个测试程序，
演示如何打印欢迎语句。
作者：小明
日期：2025年6月2日
'''

print("欢迎学习 Python 注释！")

📌 特点：

• 可跨多行
• 通常用于较长的说明或临时屏蔽代码块
• 不会影响程序运行

---

四、文档字符串（Docstring）

文档字符串是写在模块、类、函数定义第一行的注释，用于描述其功能和使用方式。常用于自动生成文档。

✅ 函数 Docstring 示例：

def greet(name):
    """
    向用户打招呼
    
    参数:
        name (str): 用户名
        
    返回:
        None
    """
    print(f"你好，{name}！")

在 PyCharm 或 IPython 中输入 help(greet) 即可查看该文档字符串。

✅ 模块 Docstring 示例：

"""
这个模块包含一些基础函数
用于演示注释的使用
"""

def say_hello():
    print("Hello!")

📌 推荐格式：PEP 257 - Docstring Conventions
常见文档格式有：Google Style、NumPy/SciPy Style、Sphinx reStructuredText 等。

---

五、注释的最佳实践

场景	建议
功能说明	注释应清晰说明代码的功能、目的
调试标记	使用 # TODO:、# FIXME: 等标记便于追踪
版本更新	记录修改人、时间、修改内容
接口说明	对函数参数、返回值进行详细说明
避免冗余	不要写无意义的注释，如 i += 1 # i 加 1

---

⚠️ 注意事项

• 注释不是越多越好，而是要准确、简洁、必要
• 修改代码时应同步更新相关注释
• 使用中文或英文保持统一（建议英文）
• 不要把注释当作“代码备份”，要用 Git 等版本控制工具
• 文档字符串应遵循 PEP8 和标准格式（如 Google Style）

---

🧪 实际案例分析

📌 场景：编写一个带完整注释的函数

def calculate_area(radius):
    """
    计算圆的面积
    
    参数:
        radius (float): 圆的半径
        
    返回:
        float: 圆的面积，保留两位小数
        
    异常:
        如果 radius 为负数，抛出 ValueError
    """
    if radius < 0:
        raise ValueError("半径不能为负数")  # 检查输入是否合法
    
    area = 3.14159 * radius ** 2
    return round(area, 2)  # 返回保留两位小数的结果

✅ 使用 help(calculate_area) 可查看完整的函数说明：

>>> help(calculate_area)
Help on function calculate_area in module __main__:

calculate_area(radius)
    计算圆的面积
    
    参数:
        radius (float): 圆的半径
        
    返回:
        float: 圆的面积，保留两位小数
        
    异常:
        如果 radius 为负数，抛出 ValueError

📌 效果：

• 其他开发者可以快速了解函数用途
• IDE（如 PyCharm）会自动提示参数和返回值
• 可配合 Sphinx 自动生成 HTML 文档