Python(一) 基础语法：注释和文档字符串

一、为什么要学习注释和文档字符串

初学 Python 时，我们很容易把注意力放在变量、判断、循环、函数这些“会运行”的代码上。可是一个程序要想长期好用、好改、好教，光能运行还不够，还要让人看得懂。

注释和文档字符串就是帮助人理解代码的文字说明。

简单来说：

注释：主要写给读代码的人看，用来解释代码为什么这样写、某段代码的作用是什么。
文档字符串：也是写给人看的，但它通常用来说明模块、函数、类或方法的用途，可以被 Python 工具读取。

它们不会直接改变程序的计算结果，但会明显影响代码的可读性和可维护性。

二、注释的定义

注释是程序中不会被 Python 当作代码执行的说明文字。

在 Python 中，注释使用井号 # 开头。从 # 开始，一直到这一行结束，都会被 Python 解释器忽略。

例子：

# 这是一个注释
print("Hello, Python")

运行时，Python 只会执行：

print("Hello, Python")

# 这是一个注释 不会参与运行。

三、注释的使用方法

1. 单行注释

单行注释就是单独占一行的注释，通常用来说明下面一行或下面一小段代码的作用。

# 计算两个数的和
a = 10
b = 20
total = a + b
print(total)

这类注释适合用在代码块前面，让学生或读者先知道下面代码要做什么。

2. 行尾注释

行尾注释写在一行代码的后面，用来补充说明这一行代码。

age = 18  # 用户年龄
price = 9.9  # 商品单价

行尾注释适合解释变量的含义、单位或特殊处理。

不过要注意，行尾注释不要写得太长，否则代码会变得拥挤。

不推荐：

score = 90  # 这里定义了一个变量 score，用来保存学生这一次考试的成绩，后面会根据这个成绩判断等级

更推荐：

# 根据学生成绩判断等级
score = 90

3. 多行注释

Python 没有专门的“多行注释语法”。如果要写多行注释，最常见、最推荐的方法是每一行都使用 #。

# 下面这段代码用于判断用户是否成年。
# 如果年龄大于等于 18，就输出“已成年”。
# 否则输出“未成年”。
age = 16

if age >= 18:
    print("已成年")
else:
    print("未成年")

这种写法清晰、稳定，也容易被编辑器识别。

4. 临时注释代码

在调试程序时，有时我们想暂时让某一行代码不运行，可以用 # 把它注释掉。

print("程序开始")
# print("这一行暂时不运行")
print("程序结束")

这在学习和调试时很常见。

但是在正式代码中，不建议长期保留大量被注释掉的旧代码。因为别人看到后会疑惑：

这段代码以后还要用吗？
是忘记删除了吗？
删除会不会出问题？

如果确定不用了，就应该删掉。

四、注释的注意事项

1. 注释应该解释“为什么”，不只是重复“做什么”

坏注释：

x = x + 1  # x 加 1

这句注释没有提供新信息，因为代码本身已经很清楚。

好注释：

x = x + 1  # 统计已经处理过的学生人数

这句注释说明了变量变化的业务含义，更有价值。

2. 代码能看懂的地方，不必强行写注释

有些代码本身已经足够清楚，不需要注释。

name = "小明"
age = 18
print(name, age)

这段代码很直观，不需要每一行都解释。

如果注释太多，反而会干扰阅读。

3. 注释要和代码保持一致

注释最怕“过期”。

比如：

# 判断用户是否成年
age = 15

if age >= 16:
    print("可以参加活动")

这里注释写的是“是否成年”，但代码判断的是 age >= 16，这就会让人困惑。

修改代码时，也要检查相关注释是否需要同步修改。

4. 不要在注释里写无关内容

不推荐：

# 老师说今天要早点下课
print("开始学习 Python")

注释应该帮助理解代码，不应该写和代码无关的闲聊内容。

5. 中文注释可以使用，但要保持表达清楚

对于中文教学场景，中文注释非常合适。

# 输入学生姓名
name = input("请输入姓名：")

实际工作中，如果团队要求英文注释，就按团队规范来；如果是课堂教学，使用中文注释更容易帮助初学者理解。

五、文档字符串的定义

文档字符串，也叫 docstring，是写在模块、函数、类或方法开头位置的字符串说明。

它通常使用三引号 """ """ 或 ''' ''' 包起来。

最常见的是使用三个双引号：

def greet():
    """输出一句问候语。"""
    print("你好，Python")

这里的：

"""输出一句问候语。"""

就是函数 greet 的文档字符串。

六、文档字符串和普通注释的区别

注释和文档字符串都能解释代码，但它们不是一回事。

对比项	注释	文档字符串
写法	使用 `#`	使用三引号字符串
是否被 Python 保存	不会保存	通常会保存到 `__doc__` 属性中
主要用途	解释代码细节	说明模块、函数、类、方法的用途
能否被 `help()` 查看	不能	可以
常见位置	代码附近	模块、函数、类、方法的第一条语句

例子：

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

print(add.__doc__)

输出：

返回两个数的和。

也可以使用：

help(add)

查看这个函数的说明。

七、文档字符串的使用位置

1. 模块文档字符串

一个 .py 文件就是一个模块。模块文档字符串一般写在文件最开头，用来说明这个文件的整体作用。

"""学生成绩管理示例。

本模块演示如何保存学生姓名、成绩，并根据成绩判断等级。
"""

def get_level(score):
    """根据成绩返回等级。"""
    if score >= 90:
        return "优秀"
    elif score >= 60:
        return "及格"
    else:
        return "不及格"

模块文档字符串适合说明：

这个文件是做什么的
主要包含哪些功能
使用时需要注意什么

2. 函数文档字符串

函数文档字符串写在函数体的第一行，用来说明函数的功能、参数和返回值。

简单写法：

def square(number):
    """返回一个数的平方。"""
    return number * number

更完整的写法：

def divide(a, b):
    """计算 a 除以 b 的结果。

    参数：
        a: 被除数。
        b: 除数，不能为 0。

    返回：
        a / b 的计算结果。
    """
    return a / b

课堂教学中，可以先讲简单写法，再逐步引入参数和返回值说明。

3. 类文档字符串

类文档字符串写在类定义下面的第一行，用来说明这个类表示什么。

class Student:
    """表示一个学生。

    属性：
        name: 学生姓名。
        score: 学生成绩。
    """

    def __init__(self, name, score):
        self.name = name
        self.score = score

类文档字符串适合说明：

这个类代表什么对象
主要属性有哪些
这个类通常怎么使用

4. 方法文档字符串

方法就是写在类里面的函数。方法也可以有自己的文档字符串。

class Student:
    """表示一个学生。"""

    def __init__(self, name, score):
        self.name = name
        self.score = score

    def is_passed(self):
        """判断学生是否及格。"""
        return self.score >= 60

八、文档字符串的常见写法

1. 单行文档字符串

如果说明很短，可以写成一行。

def say_hello():
    """打印问候语。"""
    print("你好")

适合简单函数。

2. 多行文档字符串

如果函数比较复杂，就使用多行文档字符串。

def calculate_total(price, count, discount):
    """计算商品总价。

    参数：
        price: 商品单价。
        count: 商品数量。
        discount: 折扣，例如 0.8 表示八折。

    返回：
        折扣后的总价。
    """
    return price * count * discount

多行文档字符串的常见结构是：

第一行：简短说明功能。
空一行：让结构更清晰。
后面几行：说明参数、返回值、异常或使用注意事项。

3. 带异常说明的文档字符串

如果函数可能主动抛出异常，可以在文档字符串里说明。

def get_item(items, index):
    """根据下标获取列表中的元素。

    参数：
        items: 要查询的列表。
        index: 元素下标。

    返回：
        指定下标位置的元素。

    异常：
        IndexError: 当下标超出列表范围时抛出。
    """
    return items[index]

这样使用函数的人就能提前知道可能出现什么问题。

九、三引号字符串是不是多行注释

这是初学者最容易混淆的地方。

很多人会这样写：

"""
这里看起来像多行注释。
Python 好像也没有执行它。
"""

print("Hello")

这段代码通常能运行，所以有人说“三引号可以写多行注释”。

但更准确地说：三引号写出来的是字符串，不是注释。

只是在某些位置，如果这个字符串没有赋值给变量，也没有被使用，它看起来像是“没有效果”。但是它仍然是一个字符串表达式。

真正的注释是：

# 这里是多行注释的第一行
# 这里是多行注释的第二行
# 这里是多行注释的第三行
print("Hello")

教学时可以这样提醒学生：

# 才是 Python 的注释符号。
三引号用于写字符串。
当三引号字符串出现在模块、函数、类或方法的第一条语句位置时，它才是文档字符串。
不建议把三引号字符串当作普通多行注释长期使用。

十、文档字符串的注意事项

1. 文档字符串必须放在正确位置

函数文档字符串必须是函数体中的第一条语句。

正确：

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

不正确：

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

第二种写法中，三引号字符串不再是函数的文档字符串，只是一个没有被使用的字符串。

2. 注意缩进

文档字符串属于函数、类或方法内部时，必须和代码块保持一致的缩进。

正确：

def hello():
    """打印问候语。"""
    print("你好")

错误：

def hello():
"""打印问候语。"""
    print("你好")

第二种写法会因为缩进错误导致程序无法运行。

3. 文档字符串不要写得太空泛

不推荐：

def add(a, b):
    """这是一个函数。"""
    return a + b

这句话没有说明函数到底做什么。

4. 参数、返回值要说明清楚

当函数有参数和返回值时，文档字符串最好说明它们的含义。

def get_discount_price(price, discount):
    """计算折扣后的价格。

    参数：
        price: 原价。
        discount: 折扣，例如 0.8 表示八折。

    返回：
        折扣后的价格。
    """
    return price * discount

这样别人不用阅读函数内部代码，也能知道怎么调用它。

5. 文档字符串要跟着代码一起更新

如果代码功能变了，文档字符串也要改。

比如原来函数是计算总价：

def calculate(price, count):
    """计算商品总价。"""
    return price * count

后来加入了折扣：

def calculate(price, count, discount):
    """计算商品总价。"""
    return price * count * discount

这时文档字符串就不够准确了，应该改成：

def calculate(price, count, discount):
    """计算商品折扣后的总价。"""
    return price * count * discount

十一、教学中可以这样讲

可以把注释和文档字符串用一个生活化比喻讲给学生：

注释像是写在书页旁边的批注，主要帮助读者理解某几行内容。

文档字符串像是一本书每一章开头的简介，告诉读者这一章主要讲什么、怎么使用。

再换成代码中的说法：

注释：解释局部代码。
文档字符串：介绍整体功能。

例子：

"""学生成绩判断程序。

这个程序演示如何根据学生分数判断成绩等级。
"""


def get_grade(score):
    """根据成绩返回等级。

    参数：
        score: 学生分数。

    返回：
        成绩等级，例如“优秀”“及格”“不及格”。
    """
    # 90 分及以上认为是优秀
    if score >= 90:
        return "优秀"

    # 60 分及以上认为是及格
    if score >= 60:
        return "及格"

    return "不及格"


student_score = 85
grade = get_grade(student_score)
print(grade)

这段代码中：

文件开头的三引号内容是模块文档字符串。
get_grade 函数内部第一行三引号内容是函数文档字符串。
# 90 分及以上认为是优秀 是普通注释。
# 60 分及以上认为是及格 也是普通注释。

十二、课堂练习

练习 1：给代码添加注释

请给下面代码添加合适的注释：

name = input("请输入姓名：")
score = int(input("请输入成绩："))

if score >= 60:
    print(name, "通过考试")
else:
    print(name, "没有通过考试")

参考答案：

# 输入学生姓名
name = input("请输入姓名：")

# 输入学生成绩，并转换为整数
score = int(input("请输入成绩："))

# 判断学生是否通过考试
if score >= 60:
    print(name, "通过考试")
else:
    print(name, "没有通过考试")

练习 2：给函数添加文档字符串

请给下面函数添加文档字符串：

def max_number(a, b):
    if a > b:
        return a
    return b

参考答案：

def max_number(a, b):
    """返回两个数中较大的一个。

    参数：
        a: 第一个数。
        b: 第二个数。

    返回：
        a 和 b 中较大的值。
    """
    if a > b:
        return a
    return b

练习 3：判断哪些是文档字符串

阅读下面代码，判断哪些三引号字符串是真正的文档字符串。

"""这是模块文档字符串。"""


def test():
    print("开始")
    """这是函数文档字符串吗？"""
    print("结束")


def hello():
    """这是函数文档字符串。"""
    print("你好")

答案：

文件最开头的 """这是模块文档字符串。""" 是模块文档字符串。
test 函数里的三引号字符串不是函数文档字符串，因为它不是函数体中的第一条语句。
hello 函数里的 """这是函数文档字符串。""" 是函数文档字符串。

十三、总结

注释和文档字符串都是让代码更容易理解的重要工具。

注释使用 #，主要解释代码细节。它适合说明某一行、某几行代码为什么这样写，或者某个变量、判断条件的含义。

文档字符串使用三引号，通常写在模块、函数、类或方法的开头。它适合说明整体功能、参数、返回值和使用注意事项，并且可以被 help() 或 __doc__ 查看。

# 是真正的注释符号。
三引号本质上是字符串，不是普通注释。
放在模块、函数、类或方法开头的三引号字符串，才叫文档字符串。

写好注释和文档字符串，不是为了让代码显得复杂，而是为了让自己和别人以后更轻松地读懂代码。