Python3 注释

Python3 学习笔记 · 整理自菜鸟教程

一句话

注释是给人看的说明文字，解释器会忽略它，用于记录思路、禁用代码和生成文档。

要点

• 单行注释：以 # 开头，到行尾结束。
• 多行注释：用三个单引号 '''...''' 或三个双引号 """...""" 包裹。
• 文档字符串：函数、类、模块的第一条字符串是 docstring，可用 help() 或 __doc__ 读取。
• 注释不是字符串：三引号本质是字符串字面量，只是未被赋值时像注释。
• PEP 8 规范：# 后加一个空格，行内注释与代码至少隔两个空格。
• 禁用代码：临时注释掉一段代码，便于调试，但别长期保留。
• 编码声明：Python3 默认 UTF-8，一般不需要写 # -*- coding: utf-8 -*-。

语法 / 常用方法

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# 这是一条单行注释，解释器会忽略

"""这是多行注释，
可以跨多行，
通常用于文件或函数的说明。"""


def add(a, b):
    """两数相加并返回结果。

    参数:
        a: 第一个数
        b: 第二个数
    返回:
        两数之和
    """
    return a + b


class Point:
    """表示平面上的一个点。"""
    pass


# 行内注释：与代码之间建议留两个空格
count = 0  # 计数器初值

# 读取文档字符串
print(add.__doc__)          # 打印 add 的文档
print(Point.__doc__)        # 表示平面上的一个点。

# 用 help 查看更完整的文档（交互式可用）
# help(add)

# 注释临时禁用代码（调试用）
# print("这一行被注释掉了")
print("这一行会执行")

print(add(3, 4))            # 7

易错点

• 三引号不是真注释：它是字符串字面量，出现在函数第一行才算 docstring。
• 文档字符串必须是第一条语句：函数体里第一个语句若不是字符串，__doc__ 为 None。
• 行内注释开头：# 前面若有代码，# 之后全是注释，别把代码写到注释后面。
• 别长期注释掉大段代码：容易遗留死代码，建议直接删除，需要时从版本控制找回。
• # 与 shebang：脚本首行 #!/usr/bin/env python3 是特殊注释，要放在最顶部。
• 编码声明位置：如需声明编码，必须放在文件第一或第二行才生效。