Python - 文档字符串（Docstrings）

你好，有抱负的Python程序员们！今天，我们将深入探讨文档字符串的奇妙世界。作为你友好的计算机科学老师，我很高兴能引导你了解Python编程的这个基本方面。所以，拿上你最喜欢的饮料，舒服地坐好，让我们一起踏上这个学习冒险之旅！

Python - Docstrings

Python中的文档字符串

想象一下你在写日记。在每一篇日记的开头，你可能会简要地记下那天发生的事情。嗯，Python中的文档字符串有点像那样！它们是描述代码块功能的特殊字符串，使你（和其他人）以后更容易理解你的代码。

在Python中，文档字符串被三引号（""" 或 '''）包围，并且放在函数、类或模块定义之后的立即位置。让我们看一个简单的例子：

def greet(name):
"""这个函数向作为参数传入的人打招呼"""
print(f"Hello, {name}!")

在这个例子中，三引号之间的行就是我们的文档字符串。它简要地说明了greet函数的作用。

单行文档字符串

对于简单的函数或类，单行文档字符串可能就是你需要的。这里有一个例子：

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

这个文档字符串简短而甜美，只用一行就清楚地告诉我们这个函数的作用。

多行文档字符串

对于更复杂的函数或类，你可能需要一个多行文档字符串。这些通常包括一个摘要行，后面是一个空行，然后是更详细的信息。让我们看一个例子：

def calculate_area(length, width):
"""
计算矩形的面积。

参数:
length (float): 矩形的长度
width (float): 矩形的宽度

返回:
float: 矩形的面积
"""
return length * width

这个多行文档字符串提供了关于函数参数和返回值的更详细信息。

模块的文档字符串

模块也可以有文档字符串！这些被放在文件的最开始位置。例如：

"""
这个模块包含了用于几何计算的实用函数。
它包括用于计算各种形状的面积和大小的函数。
"""

def calculate_circle_area(radius):
# 函数实现在这里

类的文档字符串

类也可以有文档字符串。这些被放在类定义之后的立即位置：

class Rectangle:
"""
表示矩形的类。

属性:
length (float): 矩形的长度
width (float): 矩形的宽度
"""

def __init__(self, length, width):
self.length = length
self.width = width

访问文档字符串

文档字符串的一个很酷的地方是你可以以编程方式访问它们。Python将文档字符串存储为函数、类或模块的__doc__属性。以下是如何访问它的方法：

def greet(name):
"""这个函数向作为参数传入的人打招呼"""
print(f"Hello, {name}!")

print(greet.__doc__)

这将输出：这个函数向作为参数传入的人打招呼

编写文档字符串的最佳实践

现在我们知道如何编写文档字符串，让我们谈谈一些最佳实践：

保持简洁但提供信息
使用正确的语法和标点
在你的风格中保持一致
包含关于函数参数和返回值的信息
对于类，描述重要的属性和方法

Google风格的文档字符串

Google有自己的文档字符串风格指南。这里有一个例子：

def divide(a, b):
"""除以两个数字。

参数:
a (int): 被除数。
b (int): 除数。

返回:
float: 除法的结果。

引发:
ZeroDivisionError: 如果b是0。
"""
if b == 0:
raise ZeroDivisionError("不能除以零")
return a / b

NumPy/SciPy风格的文档字符串

如果你在使用科学Python库，你可能会遇到NumPy/SciPy风格：

def calculate_mean(numbers):
"""
计算数字列表的算术平均值。

参数
----------
numbers : list
数字列表。

返回
-------
float
输入列表的算术平均值。
"""
return sum(numbers) / len(numbers)

Sphinx风格的文档字符串

Sphinx是Python的一个流行的文档生成器。它的风格与reStructuredText格式类似：

def fibonacci(n):
"""
生成一个斐波那契序列直到n。

:param n: 要生成的斐波那契数字的数量
:type n: int
:return: 斐波那契数字的列表
:rtype: list
"""
sequence = [0, 1]
while len(sequence) < n:
sequence.append(sequence[-1] + sequence[-2])
return sequence[:n]

文档字符串与注释

你可能会想，“文档字符串和普通注释有什么区别？”这是一个很好的问题！让我们分解一下：

语法：文档字符串使用三引号，而注释使用#。
位置：文档字符串紧跟在定义之后，而注释可以放在任何地方。
目的：文档字符串解释代码的作用，注释解释它是如何做到的。
可访问性：文档字符串可以以编程方式访问，注释则不能。

以下是一个快速示例来说明：

def add(a, b):
"""
将两个数字相加并返回结果。
"""
# 这是一个解释我们如何进行加法的注释
return a + b  # 这是一个行内注释

就是这些，各位！我们已经涵盖了Python文档字符串的所有内容。请记住，好的文档就像为未来的你（或其他开发者）留下的面包屑轨迹。现在可能看起来像是额外的工作，但相信我，你以后会感谢自己的！

以下是我们所涉及的文档字符串风格的快速参考表：

风格	摘要	示例
单行	简短的，一行描述	`"""返回一个数字的平方。""`
多行	带有参数和返回值的详细描述	`"""计算矩形的面积。\n\n参数:\n...""`
Google	包括Args, Returns, 和 Raises部分	`"""除以两个数字。\n\n参数:\n...""`
NumPy/SciPy	使用参数和返回部分，具有更详细的格式	`"""计算数字列表的算术平均值。\n\n参数\n----------\n...""`
Sphinx	使用:param:, :type:, :return:, 和 :rtype:字段	`"""生成一个斐波那契序列直到n。\n\n:param n: ...""`

编程愉快，愿你的文档字符串始终清晰明了！

Credits: Image by storyset