Python代码注释三种写法详解：单行、多行与docstring实践

脚本专家

写代码时，注释往往被当作可有可无的东西。但真正维护过项目的人都知道，一段没有注释的代码，隔几个月再回头看，很可能连自己都看不懂。注释不是写给机器看的，而是写给下一个读代码的人——包括未来的你。好的注释能解释代码背后的意图，让维护成本大幅降低。Python提供了三种常用的注释形式，下面逐一说明。

一、单行注释：井号

单行注释以 # 开头，从 # 到行尾的内容都会被视为注释，Python解释器会直接忽略。这是最常用、最轻量的注释方式。

2. # 这是一个单行注释
3. print('Hello, World!')  # 这行打印一句话
5. # 计算1到100的和
6. total = 0
7. for i in range(1, 101):
8.     total += i  # 累加每一个数字
9. print(total)  # 输出结果：5050

复制代码

单行注释还有一个实用场景：临时禁用某一行代码。调试时，把不需要执行的代码注释掉，比删掉再恢复更安全。

2. print('这条会执行')
3. # print('这条不会执行，因为被注释掉了')
4. print('这条也会执行')

复制代码

在主流IDE中，选中多行后按 Ctrl+（Windows/Linux）或 Cmd+（Mac）可以快速注释或取消注释，配合单行注释调试非常方便。

二、多行注释：三引号

Python没有专门的多行注释语法。一种常见的做法是用三个单引号 ''' 或三个双引号 """ 将内容包裹起来，实现类似多行注释的效果。

2. '''
3. 这是一个多行注释
4. 可以跨越多行
5. Python解释器会忽略这些内容
6. '''
8. """
9. 这也是一个多行注释
10. 用双引号也是一样的效果
11. """

复制代码

需要注意的是，三引号包裹的内容本质上是一个字符串字面量，只是它没有被赋值给任何变量，所以解释器创建之后马上丢弃。严格来说，它不是真正的注释，而是“被丢弃的字符串字面量”。但实际开发中，大家都把它当作多行注释使用。

三引号注释常用于三种场景：函数或模块顶部的说明、临时注释掉一大段代码、以及编写文档字符串。

三、文档字符串（docstring）

文档字符串是Python中特殊的“注释”形式，用三引号包裹，写在模块、类或函数的第一行。与普通注释最大的区别是，文档字符串可以被程序动态访问。

2. def greet(name, greeting='你好'):
3.     '''向指定的人打招呼。
5.     Args:
6.         name: 被问候的人的名字
7.         greeting: 问候语，默认为“你好”
9.     Returns:
10.         str: 完整的问候语字符串
11.     '''
12.     return f'{greeting}，{name}！'
14. # 通过 __doc__ 属性访问文档字符串
15. print(greet.__doc__)
17. # 也可以用 help() 查看格式化的文档
18. help(greet)

复制代码

有了文档字符串，函数和类的使用者不必阅读实现细节，就能清楚知道参数的格式和返回值。编写自定义函数或类时，花一分钟写一个简短docstring，长期收益很大。

四、什么时候该写注释

不是所有代码都需要注释。判断标准很简单：注释应该解释“为什么”，而不是重复“是什么”。

无意义的注释只会产生噪音：

2. x = x + 1  # 将x加1

复制代码

有价值的注释解释了原因：

2. x = x + 1  # 补偿索引偏移，因为用户输入的序号从1开始而不是0

复制代码

以下场景最好写注释：

1. 算法逻辑不直观时。例如埃拉托斯特尼筛法，需要说明为什么只检查到 sqrt(n)。

2. # 使用埃拉托斯特尼筛法找出所有质数
3. def sieve_of_eratosthenes(n):
4.     is_prime = [True] * (n + 1)
5.     is_prime[0] = is_prime[1] = False
6.     # 只需检查到sqrt(n)，因为如果n是合数，它必定有一个因子小于等于sqrt(n)
7.     for i in range(2, int(n ** 0.5) + 1):
8.         if is_prime[i]:
9.             for j in range(i * i, n + 1, i):
10.                 is_prime[j] = False
11.     return [i for i in range(2, n + 1) if is_prime[i]]

复制代码

2. 函数存在特殊限制或前置条件。比如二分查找要求输入列表已排序，注释可以提醒调用者。

3. 针对特定bug的修复代码。比如为了避免平台差异而使用 os.path.join，这时注释能解释为什么不用硬编码路径。

4. 使用 TODO、FIXME、HACK 标记待办事项或临时方案。

2. # TODO: 这里的错误处理需要完善，目前只在理想情况下工作
3. # FIXME: 当用户名为空时会崩溃，需要添加空值检查
4. # HACK: 这是一个临时方案，等后端接口好了之后要重构

复制代码

相反，如果代码本身已经很清晰，或者可以通过良好命名表达意图，就不需要额外注释。比如函数名 calculate_average_score，一眼就能看出是计算平均分，不必再加注释。一段复杂逻辑如果能拆分成多个小函数，函数名本身就是最好的注释。

五、注释的黄金法则

核心原则是：注释解释“为什么”，代码说明“是什么”。好的注释能补充代码之外的背景信息，比如业务规则、性能考虑和已知问题。

另一个重要原则是：注释必须与代码保持同步。过时的注释比没有注释更危险，因为它会误导后来的维护者。与其修改注释，不如将逻辑写得更清晰，例如用常量表代替固定税率，代码本身就能说明策略。

关于注释用中文还是英文，取决于场景。个人项目和内部团队项目，用中文沟通成本更低；开源项目或国际化团队，通常用英文；如果项目可能开源，docstring建议中英双语或直接用英文。

六、实战：有注释和无注释的差异

看一个没有注释的函数：

2. def f(d, p):
3.     r = []
4.     for k, v in d.items():
5.         if p(v):
6.             r.append(k)
7.     return r
9. data = {'a': 85, 'b': 42, 'c': 96, 'd': 58, 'e': 73}
10. print(f(data, lambda x: x >= 60))

复制代码

这个函数干了什么？需要仔细读才能明白。加上良好的命名和注释后：

2. def filter_by_criteria(data_dict, check_function):
3.     '''根据指定的筛选条件，从字典中筛选出符合条件的键。
5.     参数：
6.         data_dict (dict): 待筛选的字典，键为学生名，值为成绩
7.         check_function (callable): 筛选函数，接受一个值，返回True/False
9.     返回：
10.         list: 符合条件的键（学生名）列表
11.     '''
12.     passed_keys = []  # 存储符合条件的学生名
13.     for key, value in data_dict.items():
14.         if check_function(value):
15.             passed_keys.append(key)  # 该学生成绩符合条件，加入结果
16.     return passed_keys
18. # 学生成绩数据
19. student_scores = {
20.     '小明': 85,
21.     '小红': 42,
22.     '小刚': 96,
23.     '小丽': 58,
24.     '小华': 73
25. }
27. # 筛选条件：成绩大于等于60分
28. def is_passing(score):
29.     return score >= 60
31. passing_students = filter_by_criteria(student_scores, is_passing)
32. print(f'及格的学生有：{passing_students}')
33. print(f'及格人数：{len(passing_students)}人')
34. print(f'不及格人数：{len(student_scores) - len(passing_students)}人')

复制代码

虽然行数变多了，但可读性大幅提升，即使换一个人接手也能快速理解逻辑。

七、注释在调试中的妙用

注释也是调试时的利器。当程序出现问题时，可以用单行注释暂时屏蔽部分代码，逐步定位问题。

2. def complex_calculation(data):
3.     # 第一步：数据清洗
4.     cleaned_data = clean_data(data)
5.     print(f'清洗后数据条数：{len(cleaned_data)}')
7.     # 第二步：怀疑转换有bug，先注释掉后面，只看前面的输出
8.     # transformed_data = transform_data(cleaned_data)
9.     # print(f'转换后数据条数：{len(transformed_data)}')
11.     # 第三步：暂时返回None，等排查完bug再恢复
12.     return None

复制代码

另外，在学习或实验阶段，可以用注释保留多种实现方式，方便对比和切换：

2. # 写法一：列表推导式
3. # squared = [x**2 for x in range(10)]
5. # 写法二：map函数
6. # squared = list(map(lambda x: x**2, range(10)))
8. # 写法三：传统for循环，当前采用这种写法，最易读
9. squared = []
10. for x in range(10):
11.     squared.append(x ** 2)
12. print(squared)

复制代码

八、小结

Python中三种注释形式各有定位：单行注释适合解释局部逻辑；三引号适合多行说明或临时屏蔽代码；docstring则面向工具和API文档，是正规的文档接口。写注释时，多问自己“这里为什么这样写”，而不是“这里写了什么”。好的命名能替代一部分注释，但关键逻辑、业务规则和已知问题，仍然需要注释来记录。保持注释与代码同步，过时的注释应该及时修正或删除。从今天开始，在写代码时把注释当成代码的一部分，长期维护时会受益无穷。

热心网友7

楼主这篇写得很实在，尤其是“注释是写给下一个读代码的人——包括未来的自己”这句话，深有同感。我前阵子翻自己半年前写的脚本，没注释的地方愣是看了半天才反应过来当初为啥要那么写，加了注释的几段基本一眼就想起当时的思路。 关于三引号当多行注释用，我个人其实习惯直接用 # 逐行注释，因为有些编辑器对三引号高亮处理不一样，万一哪天粗心把它赋值给变量了容易混淆。不过楼主说的“被丢弃的字符串字面量”这个说法很清楚，新手看这个应该能理解本质。 docstring部分讲得也很好，用 help() 和 __doc__ 访问这个点很实用，很多人写函数确实不太习惯开头写一段说明，但团队协作时这个太重要了。还有注释解释“为什么”而不是“是什么”那段，我觉得可以再加个例子：有些时候“是什么”也有价值，比如一些不常见的函数用法，但大概率好命名能解决一大部分问题。 最后提一个小问题：楼主示例里筛法那段代码是不是漏了个类似 `` 的初始化？我看 `is_prime = * (n + 1)` 那地方好像少了点东西，不知道是不是排版原因。总体是篇很实用的小文章，收藏了。

热心网友7

楼主写得很全面，尤其是“注释解释为什么，而不是重复是什么”这个观点，深有体会。我自己就见过很多项目里满屏“将x加1”这种注释，纯粹是噪音，反而把真正有历史背景的说明淹没了。 另外提一个小补充：关于三引号“多行注释”的坑，确实要注意，因为它本质上是个字符串，如果放在代码中间某些位置（比如表达式后面），可能不会像预期那样被忽略，甚至会影响逻辑。我一般会严格要求团队：模块/类/函数文档用docstring，临时屏蔽大段代码尽量用IDE的块注释功能（也就是每行都加#），避免误用三引号。 还有docstring的格式，楼主推荐了Args和Returns风格的描述，很好用。如果要更规范，可以提一下PEP 257或Google风格，不过对普通脚本来说，楼主这种简洁写法已经足够清晰了。

热心网友6

楼主这篇写得很实在，尤其是“注释是写给下一个读代码的人——包括未来的你”这句，深有体会。我自己就吃过没写注释的亏，几个月后看自己的代码跟看天书一样。三种注释的区分讲得清楚，特别是docstring能被程序访问这一点，很多人容易忽略。还有“注释解释为什么，而不是重复是什么”那段，例子给得很直观，感觉可以直接拿来做团队规范参考了。