Python3 注释

为什么需要注释

注释是写在代码中的说明文字，帮助他人（以及未来的自己）理解代码的意图。Python 解释器会完全忽略注释，它不影响任何运行结果。

单行注释

以 # 开头，可以独占一行，也可以放在代码末尾：

# 计算半径为 5 的圆面积
r = 5                       # 半径
area = 3.14 * r ** 2        # 圆面积公式 πr²
print(area)                 # 输出：78.5

多行注释

Python 没有专门的多行注释语法，习惯用三个单引号 ''' 或三个双引号 """ 包裹多行文字。它本质上是字符串字面量，由于没有被赋值或使用，解释器会直接丢弃：

"""
这是一段"多行注释"，
常用来写较长的大段说明。
"""
print("多行文字并未输出")    # 输出：多行文字并未输出

文档字符串 docstring

函数、类或模块开头位置的字符串会被视为文档字符串，用于描述其用途，可通过 对象.__doc__ 查看：

def add(a, b):
    """返回两个数的和。"""
    return a + b

print(add.__doc__)   # 输出：返回两个数的和。
print(add(1, 2))     # 输出：3

注释规范

好注释应当说明为什么这样做，而不是复述代码在做什么（"怎么做"代码本身已能表达）：

# 反例：复述代码，纯属噪音
x = x + 1           # 把 x 加 1

# 正例：说明意图
total = total + 1   # 已售数量 +1，保持与库存统计口径一致

常用规范要点：

• 注释要与代码同步更新，过时的注释比没有注释更危险。
• 不写废话注释；变量命名清晰时往往不需要注释。
• 大段设计说明可写在模块头部的 docstring 中。

临时禁用代码

调试时常用注释"屏蔽"某些行，验证不同逻辑：

print("执行第一行")
# print("这一行被注释，不会输出")
print("执行第三行")

单行用 #，多行可用 ''' 或 """；函数与类开头的字符串是 docstring，可编程读取。注释重在传达"意图"而非复述代码。