Python 注释

注释是写给"人"看的说明文字，Python 解释器在运行时会完全忽略它们。良好的注释能让代码更易读、易维护。

为什么需要注释

• 解释为什么要这样写，而不是复述代码做了什么。
• 说明函数的用途、参数和返回值。
• 临时屏蔽某段代码以便调试。
• 记录作者、日期、修改说明等元信息。

单行注释

Python 只有一种真正的注释符号：井号 #。从 # 开始到行尾的内容都是注释。

score = 95          # 学生的考试分数
print(score)        # 输出分数

# 也可以单独占一行：

# 下面计算两个数的和
result = a + b

多行注释

Python 没有像 C++ /* */ 那样的多行注释语法。常见做法有两种：

方式一：每行都加 #

# 这是一个多行注释
# 每一行都以 # 开头
# 适合写较长的说明

方式二：使用三引号字符串

虽然三引号 ''' 或 """ 本质是字符串，但若不赋值给任何变量，解释器会直接丢弃它，因此常被当作多行注释使用：

"""
这是一段用三引号写的"多行注释"。
它不会被打印，也不会赋值给变量。
常用于文件开头或函数开头的说明。
"""

注意

这种方式其实是没有被使用的字符串字面量，并非真正的注释语法。规范的做法是把它用作文档字符串（docstring），放在模块、函数、类的开头，详见后文。

文档字符串（Docstring）

把三引号字符串写在函数、类或模块的开头，它就变成了文档字符串，可以通过 help() 或 __doc__ 读取：

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

print(add.__doc__)
help(add)

运行结果（节选）：

返回两个数的和。

用注释调试代码

调试时可以用 # 临时禁用某些代码，观察程序行为：

a = 10
b = 20

# 临时屏蔽下面这行
# c = a + b

print("a =", a)
print("b =", b)

注释的风格建议

1. 解释"为什么"而非"是什么"。不要写 x = 10 # 把 10 赋值给 x 这种废话。
2. 保持与代码同步。代码改了，注释也要跟着改，过时的注释比没有更危险。
3. 复杂逻辑前加说明，用多行注释讲清思路。
4. 文件头写元信息，团队协作常见：

"""
项目名称：Koyuki Palace
文件名：main.py
作者：Koyuki
描述：程序入口
"""

完整示例

"""
函数：add
功能：计算两个整数的和
"""


def add(a, b):
    # 直接返回两数之和
    return a + b


x = 10
y = 20
result = add(x, y)

print("x + y =", result)

运行结果：

x + y = 30