每天学点Python知识：注释

大家好，欢迎来到IT知识分享网。

在 Python 编程中，注释是一种被低估却非常重要的表达方式。它不影响程序的执行，却极大影响了代码的“可读性”和“可维护性”。你写的代码，总有一天会被别人（或者未来的你）重新阅读和修改，而一条清晰的注释，往往比几十行代码本身更有价值。

那么，Python 的注释该怎么写？又该写些什么，避免写些什么？本文就来聊聊这件“写给人看的事”。

一、Python 注释的基本语法

Python 的注释有两种形式：单行注释和多行注释（或块注释）。

1. 单行注释

最常见，用 # 开头：

# 计算圆的面积 area = 3.14 * r 2 

可以放在一行的开始，也可以放在语句的末尾：

area = 3.14 * r 2 # 这里假设 PI = 3.14 

2. 多行注释（块注释）

严格来说，Python 并没有多行注释的语法，但我们可以连续使用多个 # 来构建一个注释块：

# 以下是数据清洗的步骤： # 1. 去除缺失值 # 2. 转换日期格式 # 3. 统一字段名称 

二、写什么样的注释才“有价值”？

不是所有注释都是“好注释”。很多初学者喜欢写这种：

i = 0 # 将 i 设置为 0 

这类注释属于“废话型注释”，代码已经很清楚了，不需要重复一遍。

真正有价值的注释，通常具有以下几个特点：

✅ 解释“为什么”，而不是“做什么”

代码本身已经在表达“做什么”，注释应该解释“为什么这么做”：

# 使用指数平滑代替移动平均，是为了对突变数据更敏感 smoothing = alpha * new + (1 - alpha) * old 

✅ 说明边界条件、特殊情况

# 如果订单总金额为0，则不记录到数据库（避免垃圾数据） if total_amount == 0: return 

✅ 给出使用示例（特别是函数和类）

def normalize(text): """ 将输入文本标准化，统一大小写和去除特殊符号。 示例： >>> normalize("Hello, World!") 'hello world' """ 

三、Docstring：写给人，也写给工具看

对于函数、类、模块，Python 提倡使用 文档字符串（docstring）：

def greet(name): """向用户打招呼""" print(f"Hello, {name}!") 

Docstring 是写在函数体第一行的三引号字符串。它不仅能让人更快了解函数用途，很多自动化工具（如 VS Code、PyCharm、Sphinx）也会读取它来生成文档。

你可以进一步遵循一些格式规范，比如 Google、NumPy、reStructuredText 风格，例如：

def add(a, b): """ 两数相加 Args: a (int): 第一个数 b (int): 第二个数 Returns: int: 两数之和 """ return a + b 

四、注释的最佳实践

以下是一些实用建议：

1. 不要写废话注释，比如“# 增加变量 i”；
2. 保持注释同步，如果改了代码，别忘了改注释；
3. 用简单自然的语言，写给“你一年后的自己”；
4. 中英文都可以，但要统一风格，避免中英混乱；
5. 适当留白，让注释和代码各自清晰可辨；
6. 别注释掉错误的代码块当“备份”，用版本控制（如 Git）来管理历史。

写在最后

注释不是一种技术，它是一种责任。它意味着你尊重阅读代码的人，也尊重你未来的自己。Python 鼓励“清晰胜于聪明”，写好注释，恰恰是这种精神的体现。

不要等到项目烂尾时才发现“谁写的这段代码我看不懂”，因为那个人，可能就是你自己。