7 注释与文档字符串

在学习 Python 的过程中，掌握基础语法是很重要的一步。在这篇文章中，我们将重点关注 Python 中的 注释 和 文档字符串。这两个概念不仅能帮助你理解和组织代码，还能提高代码的可读性和可维护性。让我们一起深入探索这些内容吧。

注释

在 Python 中，注释是用于解释代码或记录信息的文本，它不会被 Python 解释器执行。注释的主要目的是提高代码的可读性，帮助其他开发者（或将来的自己）理解代码的功能和逻辑。

单行注释

单行注释使用 # 开头。该行的 # 后面的所有内容都会被视为注释。例如：

# 这是一个单行注释，下面的代码将输出 Hello, World!
print("Hello, World!")  # 输出 Hello, World!

在这个例子中，注释 # 这是一个单行注释 是对代码的说明，不会被执行。

多行注释

虽然 Python 并没有专门的多行注释语法，但我们可以使用多个单行注释或使用多行字符串（''' 或 """）来达到相同效果。下面是用多行字符串作为注释的示例：

'''
这是一个多行注释
可以用于解释比较复杂的代码
'''
print("Hello, World!")

使用多行字符串的方式，虽然它并不是严格的注释，但在不被赋值的情况下，它会被 Python 忽略，因此可以用作注释。

文档字符串

文档字符串（docstring）是用来描述模块、类和函数功能的特殊字符串。与普通注释不同，文档字符串会在函数被调用时生成，并可以通过 help() 函数或 .__doc__ 属性访问。它们的定义用三重引号（''' 或 """）表示，通常放在函数或类的开头。

定义函数的文档字符串

下面是一个简单的函数示例，带有文档字符串：

def add(a, b):
    """
    求两个数的和。

    参数:
    a -- 第一个数字
    b -- 第二个数字

    返回:
    两个数的和
    """
    return a + b

# 调用函数，并查看文档字符串
print(add(2, 3))       # 输出 5
print(add.__doc__)     # 输出函数的文档字符串

在这个示例中，add 函数的文档字符串告诉我们这个函数的用途、参数和返回值。适当的文档字符串对于理解和维护代码至关重要。

小结

掌握注释和文档字符串是 Python 编程的基础。良好的注释可以使代码更易于理解，而恰当的文档字符串则能极大地方便他人在使用你的代码时获取必要的信息。在你的编程旅程中，切记遵循良好的编码规范，注重代码的可读性和可维护性。

下一步

在上一篇文章中，我们讨论了如何搭建 Python 环境，并介绍了简单的 IDE。现在我们进一步学习了 Python 的注释和文档字符串。在下一篇文章中，我们将讨论基本数据输出的方法，帮助你更好地展示和使用数据。敬请期待！