python

关注公众号 jb51net

关闭
首页 > 脚本专栏 > python > Python注释

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

作者：難釋懷

在Python编程语言中注释是必不可少的一部分,它有助于提高代码的可读性和维护性,这篇文章主要介绍了Python中注释使用方法的相关资料,需要的朋友可以参考下

一、前言

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

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

本文将带你深入了解：

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

二、什么是注释？

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

在 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）

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

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

函数 docstring 示例：

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

查看 docstring：

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注释内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:
阅读全文