本教程展示了如何使用文档字符串来增强 Python 代码的可读性，文档字符串是传统注释的替代方案，用于提供清晰、全面的文档。
译自 Documenting Python Code With Docstrings，作者 Jack Wallen。
文档化代码 是必不可少的，尤其是在团队合作开发项目时。如果没有适当的文档，团队中的其他开发人员可能无法理解你试图用代码块实现的目标，这会导致瓶颈。在一个效率至上的世界里，避免工作流程中的减速至关重要。
你如何做到这一点？
文档化你的代码。
当然，始终存在传统的代码文档化方法，看起来像这样：
def hello_world():
# A simple comment preceding a simple print statement
print("Hello World")上面我们有一个简单的 Hello World 应用程序，只有一个由单个 # 字符定义的注释。如果该注释换行到第二行，你可以添加另一个 # 字符，如下所示：
def hello_world():
# A simple comment preceding a simple print statement
# but we've modified it to print out Hello New Stack
print("Hello New Stack")这是一种简单的代码注释方法，但不是唯一的方法。让我向你介绍另一种文档化 Python 代码 的方法，即 docstring。
当你知道你的注释将占用多行，并且不想用一列 # 字符来使代码混乱时，docstring 是一种很好的注释方法。
本质上，docstring 是一种特殊的注释类型，用于描述代码块的目的和/或功能。这可以用于模块、类、方法和/或函数，并放置在每个定义的后面。
要使用 docstring，你可以在代码块的开头和结尾放置三个双引号 (""")，如下所示：
def write_to_file(filename, content):
"""
Writes the given content to a specified file.
Parameters:
filename (str): The name of the file to write to.
content (str): The content to write into the file.
Returns:
None
"""
with open(filename, 'a') as file:
file.write(content + '\n') # Write content followed by a newline在上面的示例中，我们的 docstring 是：
Writes the given content to a specified file.
Parameters:
filename (str): The name of the file to write to.
content (str): The content to write into the file.
Returns:
None如你所见，顶部和底部都有三个双引号，这表示它是 Python 的 docstring。以下是一个完整的应用程序（它接收用户输入并将其写入文件），其中包含两个 docstring 以及常规注释：
# user_input_to_file.py
def write_to_file(filename, content):
"""
Writes the given content to a specified file.
Parameters:
filename (str): The name of the file to write to.
content (str): The content to write into the file.
Returns:
None
"""
with open(filename, 'a') as file:
file.write(content + '\n') # Write content followed by a newline
def main():
"""
Main function that prompts the user for input and writes it to a file.
Returns:
None
"""
# Prompt the user for input
user_input = input("Please enter some text to save to the file: ")
# Define the filename
filename = "user_input.txt"
# Write the user input to the file
write_to_file(filename, user_input)
# Inform the user that the input has been saved
print(f"Your input has been saved to '{filename}'.")
if __name__ == "__main__":
# Execute the main function
main()Docstring 也可以占用一行，如下所示：
"""This is my comment for Python code"""需要注意的是，与常规注释一样，Python 标准库要求代码行不超过 79 个字符，Python 代码的样式指南建议 docstring 的行长限制为 72 个字符。这意味着注释的单行不应超过 72 个字符，这就是 docstring 重要的原因。当你的注释需要多行来解释你正在做什么时，你可以使用 # 字符在每行之前添加一个 # 字符，或者使用 docstring。
但是，典型的最佳实践表明，docstring 通常用于解释对象。对于其他代码片段，请使用传统的注释。Docstring 通常包含以下组件：
- 一行摘要。
- 摘要下方的一行空白。
- 进一步的阐述。
- 另一行空白。
我们在上面的代码中已经看到了这一点。例如：
"""
Main function that prompts the user for input and writes it to a file.
Returns:
None
"""第一行是摘要，后面跟着一行空白。接下来是阐述，后面跟着结束的 “””。要正确完成 docstring，在结束的 “”” 和下一行代码之间应该有一个空格。
然后是类 docstring，用于解释你创建的类。类 docstring 包含以下内容：
- 类功能的简要摘要。
- 属性和方法的描述。
- 任何重要的注意事项或使用示例。
以下是一个类 docstring 的示例：
class Circle:
"""
A class to represent a circle.
Attributes:
radius (float): The radius of the circle.
Methods:
area(): Returns the area of the circle.
circumference(): Returns the circumference of the circle.
"""
def __init__(self, radius):
self.radius = radius
def area(self):
"""Calculates the area of the circle."""
return 3.14159 * (self.radius ** 2)
def circumference(self):
"""Calculates the circumference of the circle."""
return 2 * 3.14159 * self.radius如你所见，我们有一个多行类 docstring 和两个单行 docstring。
你可以使用其他 docstring，例如：
- 包和模块 docstring：列出导出的模块和子包。这些类似于类 docstring，只是用于模块及其内部的函数。
- 脚本 docstring：描述整个 Python 脚本或模块的总体目的和功能的 docstring。
这就是你对 Python docstring 的介绍。使用这些方法可以确保你的代码易于阅读和理解，这使得它们成为必须的，因为在多个团队成员必须参与你编写的代码的项目中，你不想让你的代码被多个传统的注释块弄得乱七八糟。