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

一、前言

在编程中，注释（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 并没有专门的“多行注释”语法，但可以通过以下两种方式实现：

方法一：多个 # 号逐行注释

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

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

方法二：使用三引号 ''' 或 """ 包裹（推荐用于文档说明）

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

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

五、文档字符串（docstring）

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

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

函数 docstring 示例：

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

查看 docstring：

help(greet)

输出：

Help on function greet in module __main__:

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

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

六、注释的最佳实践

七、常见误区与注意事项

八、总结对比表

九、结语

到此这篇关于Python中注释使用方法举例详解的文章就介绍到这了,更多相关Python注释内容请搜索China编程(www.chinasem.cn)以前的文章或继续浏览下面的相关文章希望大家以后多多支持China编程(www.chinasem.cn)！