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 文档

🧩 拓展练习（动手实践）

  1. 编写一个函数 add(a, b)，并为其添加完整的文档字符串，包括参数说明和返回值。
  2. 创建一个多行注释，说明你正在开发的一个小程序的功能与思路。
  3. 在 PyCharm 中使用 Ctrl + / 快捷键快速注释/取消注释多行代码。
  4. 使用 # TODO: 注释标记尚未完成的功能，并尝试在任务面板中查看。
  5. 使用 Sphinx 或其他工具将你的模块 docstring 生成 HTML 文档。

📚 推荐阅读

🧭 下一步建议

  • 下一章学习内容：《Python 变量与基本数据类型》
  • 深入理解变量命名规范与动态类型机制
  • 学习使用 PyCharm 的智能注释提示功能
  • 探索如何通过注释提高代码可读性与可维护性
  • 尝试使用 Sphinx 自动生成项目文档

如果你希望我为你提供：

  • 注释模板文件（Google Style / NumPy Style）
  • PyCharm 注释快捷键汇总表
  • 自动提取 docstring 的脚本
  • 更多实战项目练习题（如函数封装+注释+文档生成）

欢迎随时告诉我 😊

posted @ 2025-05-27 23:56  红尘过客2022  阅读(131)  评论(0)    收藏  举报