Python中注释使用方法举例详解

目录

• 一、前言
• 二、什么是注释？
• 示例：
• 三、单行注释
• 语法：以 # 开头，后面的内容为注释内容
• 示例：
• 示例：
• 四、多行注释
• 方法一：多个 # 号逐行注释
• 方法二：使用三引号 ''' 或 """ 包裹（推荐用于文档说明）
• 五、文档字符串（docstring）
• 函数 docstring 示例：
• 查看 docstring：
• 六、注释的最佳实践
• 七、常见误区与注意事项
• 八、总结对比表
• 九、结语

在编程中，注释（Comment） 是一段不会被程序执行的文本，它的主要作用是：

• 解释代码逻辑，便于他人或自己日后理解；
• 调试代码，临时禁用某些代码行；
• 生成文档说明（如使用 Sphinx 工具）；
• 提升代码可读性与维护性；

Python 作为一门强调可读性的语言，对注释的支持非常友好。无论是单行注释还是多行注释，Python 都提供了简洁清晰的语法支持。

本文将带你深入了解：

• 注释的基本概念；
• 单行注释与多行注释的写法；
• 文档字符串（docstring）的使用；
• 注释的最佳实践；
• 常见误区与注意事项；

掌握好注释的使用，不仅能让你写出更清晰易懂的代码，也能帮助团队协作更加高效！

注释是写给程序员看的说明文字，编译器/解释器会忽略它。

在 Python 中，注释不会影响程序的运行结果，但它对于理解代码逻辑至关重要。

# 这是一个简单的加法函数
def add(a, b):
    return a + b

# 定义一个变量 name，并赋值 "Alice"
name = "Alice"

# 计算两个数的和
result = 10 + 20

📌 注意事项：

• # 后面可以有空格；
• # 可以出现在代码行末，用于注释当前行的一部分；

x = 5  # 初始化 x 的值为 5

Python 并没有专门的“多行注释”语法，但可以通过以下两种方式实现：

# 这是第一行注释
# 这是第二行注释
# 这是第三行注释
print("Hello, Python!")

📌 适用于少量多行注释或临时调试。

'''
这是一个多行注释，
通常用于模块、类或函数的说明。
'''
print("Hello, Python!")

📌 注意：这种形式虽然不是真正的“注释”，但由于没有实际执行意义，常被当作注释使用。

文档字符串（docstring）是一种特殊的多行注释，用于描述模块、类、函数或方法的功能。

它是 Python 社区广泛使用的标准做法，尤其配合工具如 Sphinx 可以自动生成 API 文档。

def greet(name):
    """
    打印欢迎信息
    
    参数:
        name (str): 用户名
    
    返回:
        None
    """
    print(f"Hello, {name}!")

help(greet)

输出：

Help on function greet in module __main__:

greet(name)
    打印欢迎信息
    
    参数:
        name (str): 用户名
    
    返回:
        None

📌 推荐格式：Google Style / NumPy Style / reST 格式等。

实践建议	说明
✅ 注释应简洁明了	不要重复代码本身的意思，而是解释“为什么这么做”
✅ 模块/函数/类要有 docstring	提高可读性和可维护性，方便后续扩展
✅ 使用英文书写注释	更利于国际化团队协作（除非项目明确要求中文）
✅ 修改代码时同步更新注释	避免误导他人
✅ 避免无意义注释	如 i = i + 1 # 加1
✅ 使用注释辅助调试	临时屏蔽代码段，快速定位问题

误区	正确做法
写太多废话注释	应该写清逻辑意图
忘记更新注释	导致注释与代码不符，产生误解
使用不规范的 docstring 格式	推荐统一风格（如 Google Style）
把注释写成代码一样	如 # 设置变量 a = 10，应该写 # 表示用户等级
在代码中间插入大段注释	可考虑移到上方或拆分函数

注释类型	写法	是否被 help() 支持	是否推荐用于文档说明
单行注释	# 注释内容	❌ 否	❌ 否
多行注释	多个 # 或三引号包裹	❌ 否（仅当三引号在函数/类顶部时才有效）	✅ 推荐三引号方式
文档字符串	三引号包裹于函数/类/模块开头	✅ 是	✅ 强烈推荐

到此这篇关于Python中注释使用方法举例详解的文章就介绍到这了,更多相关Python注释内容请搜索风君子博客以前的文章或继续浏览下面的相关文章希望大家以后多多支持风君子博客！

您可能感兴趣的文章:

• Python函数参数和注解的使用
• python 编码中为什么要写类型注解？
• Python 注解方式实现缓存数据详解