Python注释

概述

注释是程序中不被解释器执行的说明性文字，用于对代码进行解释和说明。良好的注释习惯是编程素养的重要体现，它能帮助自己和他人更好地理解代码的意图和逻辑。Python支持单行注释、多行注释和文档字符串三种注释形式，本节将详细介绍它们的使用方法。

单行注释

单行注释以#开头，从#开始到行末的内容都是注释，不会被Python解释器执行。

基本用法

# 这是第一个Python程序
print("Hello World")

行内注释

注释也可以放在代码的后面，与代码同行：

x = 10  # 定义变量x，赋值为10
print(x)  # 输出x的值

单独占行的注释

# 计算两个数的和
x = 10
y = 20
result = x + y
print(result)  # 输出结果：30

提示：单行注释#后面建议加一个空格，这是Python的编码规范（PEP 8）所推荐的。

多行注释

Python没有专门的多行注释语法，但可以使用连续的单行注释或三引号字符串来实现多行注释的效果。

方式一：连续单行注释

# 这是一段多行注释
# 用连续的#来实现多行注释的效果
# 可以写很多行内容
print("程序开始执行")

方式二：三引号字符串

使用三个单引号'''或三个双引号"""包裹的内容，如果未被赋值给变量，就相当于多行注释：

'''
这是一段多行注释
可以写很多行
用来详细说明代码的功能
'''
print("Hello World")

或者：

"""
这也是多行注释
使用双引号同样可以
效果与单引号完全相同
"""
print("Hello World")

注意：严格来说，三引号形式并不是真正的注释，而是未赋值的字符串字面量。但它在效果上等同于多行注释，因此被广泛使用。

文档字符串

文档字符串（Docstring）是Python中一种特殊的注释形式，用于为模块、函数、类和方法编写说明文档。文档字符串使用三引号包裹，放在定义的第一行。

函数文档字符串

def greet(name):
    """
    向指定的人打招呼

    参数:
        name (str): 要打招呼的人的名字

    返回:
        str: 问候语字符串
    """
    return f"Hello, {name}!"


print(greet("Alice"))

类文档字符串

class Calculator:
    """一个简单的计算器类，支持基本的四则运算"""

    def add(self, a, b):
        """计算两个数的和"""
        return a + b

模块文档字符串

在Python文件的开头使用文档字符串，可以为整个模块编写说明：

"""
math_tools.py - 数学工具模块

本模块提供常用的数学计算函数，包括：
- 加减乘除运算
- 幂运算
- 取模运算
"""

def power(base, exponent):
    """计算base的exponent次幂"""
    return base ** exponent

访问文档字符串

使用__doc__属性可以访问文档字符串：

def greet(name):
    """向指定的人打招呼"""
    return f"Hello, {name}!"


print(greet.__doc__)

也可以使用help()函数查看文档字符串：

help(greet)

注释最佳实践

1. 解释"为什么"而非"是什么"

# 好的注释：解释为什么这样计算
x = x * 1.08  # 价格上调8%

# 差的注释：重复代码做了什么
x = x * 1.08  # x乘以1.08

2. 保持注释与代码同步

注释应该随代码一起更新，过时的注释比没有注释更糟糕。

3. 避免无意义的注释

# 差的注释：无意义的注释
i = i + 1  # i加1

# 好的做法：代码自解释，不需要注释
counter += 1

4. 使用TODO标记待办事项

# TODO: 添加输入验证，处理空数据的情况
def process_data(data):
    # FIXME: 这个算法在大数据量时性能较差，需要优化
    pass

5. 复杂逻辑必须加注释

当代码逻辑复杂、不直观时，注释是帮助理解的关键。

6. 注释不宜过多

代码本身应该尽量清晰可读，注释是对代码的补充而非替代。如果代码需要大量注释才能理解，应考虑重构代码。

代码示例

示例1：带注释的简单计算程序

# 计算圆的面积
radius = 5  # 圆的半径为5
pi = 3.14159  # 圆周率
area = pi * radius ** 2  # 面积公式：πr²
print(f"圆的面积为: {area}")

示例2：使用文档字符串的函数

def calculate_bmi(weight, height):
    """
    计算BMI指数

    参数:
        weight: 体重（千克）
        height: 身高（米）

    返回:
        BMI指数（保留两位小数）
    """
    bmi = weight / (height ** 2)
    return round(bmi, 2)


bmi = calculate_bmi(70, 1.75)
print(f"你的BMI指数为: {bmi}")

示例3：多行注释说明程序功能

'''
学生成绩管理程序
版本: 1.0
功能:
    1. 录入学生成绩
    2. 计算平均分
    3. 输出成绩报告
'''

student_name = "李明"
chinese = 92
math = 88
english = 95
average = (chinese + math + english) / 3
print(f"{student_name}的平均成绩为: {average:.1f}")

注意事项

提示：注释不是代码。注释的内容不会被Python解释器执行，仅用于人类阅读。

注意：三引号不是真正的注释。三引号形式本质上是字符串字面量，只是未被赋值时效果等同于注释。在函数或类定义的第一行使用时，会被当作文档字符串存储。

注意：避免嵌套三引号。使用三引号做注释时，内部不要出现相同类型的三引号，否则会导致语法错误。

提示：注释的编码。如果注释中包含中文，确保文件以UTF-8编码保存。

规范：PEP 8规范。单行注释的#后应加一个空格，行内注释与代码之间至少加两个空格。

小结

本节我们学习了：

• 单行注释：使用#开头，适合简短说明

• 多行注释：使用连续的#或三引号'''/"""，适合大段说明

• 文档字符串：使用三引号放在定义的首行，可通过__doc__或help()访问

• 注释最佳实践：解释原因而非结果，保持与代码同步，避免无意义注释

注释是代码可读性的重要保障，养成良好注释习惯将使你的代码更易于维护和协作。

练习题

price = 199
discount = 0.85
final_price = price * discount
tax_rate = 0.13
total = final_price * (1 + tax_rate)
print(total)