Python中注释使用方法举例详解
更新时间：2025年06月28日 11:10:18 作者：難釋懷
在Python编程语言中注释是必不可少的一部分,它有助于提高代码的可读性和维护性,这篇文章主要介绍了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 并没有专门的“多行注释”语法，但可以通过以下两种方式实现：
方法一：多个 # 号逐行注释
# 这是第一行注释
# 这是第二行注释
# 这是第三行注释
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注释内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
这篇文章主要给大家介绍了关于Django处理多用户类型的相关资料，文中通过示例代码介绍的非常详细，对大家学习或者使用Django具有一定的参考学习价值，需要的朋友们下面来一起学习学习吧2019-05-05
MySQL是最流行的关系型数据库之一,Python通过多种方式可以与MySQL进行交互,下面小编就为大家详细介绍一下Python操作MySQL的常用方法和最佳实践2025-06-06
最近在学习Django配置静态文件，下面这篇文章主要给大家介绍了关于Django压缩静态文件的实现方法，文中通过示例代码介绍的非常详细，需要的朋友可以参考借鉴，下面随着小编来一起学习学习吧2018-08-08
这篇文章主要介绍了OpenCV 读取图像imread的使用详解，文章围绕主题展开详细的内容介绍，具有一定的参考价值，感兴趣的小伙伴可以参考一下2022-09-09
今天小编就为大家分享一篇对Python3.x版本print函数左右对齐详解，具有很好的参考价值，希望对大家有所帮助。一起跟随小编过来看看吧2018-12-12
在 Python 编程中，运算符是用于执行各种数学和逻辑操作的特殊符号，本文我们就深入探讨 Python 中的常见运算符，并通过丰富的案例来说明它们的用法和功能吧2023-07-07
这篇文章主要给大家分享了额python调用bash shell脚本方法,os.system(command)、os.popen(command)等方法，具有一定的参考价值，需要的小伙伴可以参考一下，希望对你有所帮助2021-12-12
这篇文章主要为大家详细介绍了python基于ID3思想的决策树，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2018-01-01
Python神经网络TensorFlow基于CNN卷积识别手写数字
这篇文章主要介绍了Python神经网络TensorFlow基于CNN卷积识别手写数字的实现示例解析，有需要的朋友可以借鉴参考下，希望能够有所帮助2021-10-10
这篇文章主要介绍了Python 局部变量global详解，文章围绕主题展开详细的内容介绍，具有一定的参考价值，需要的小伙伴可以参考一下2022-08-08
最新评论