良好的注释对于任何成功的Python项目来说都至关重要。在实际操作中，编写注释是一件困难且耗时费力的工作，因此一些开发人员并不喜欢这样做。幸运的是，借助大型语言模型（LLMs）和像ChatGPT这样的工具，您可以迅速为您的Python代码和项目编写注释文档。
Python中的注释文档写作可以通过使用docstrings来实现，然后利用这些注释来丰富项目的外部文档。ChatGPT在编写注释和外部文档方面非常有帮助。
在本教程中，您将学到以下内容：
- 如何使用不同的ChatGPT提示词生成Python注释
- 如何在使用ChatGPT生成注释时采用不同的风格
- 如何在Python注释中添加doctest测试
为了最大限度地利用本教程，你需要拥有一个ChatGPT账户，并且了解使用prompt engineering这个工具进行交互的基础知识。同时，你还需要了解如何为Python代码编写文档的基本知识。
使用ChatGPT为Python代码编写文档的优势
对于任何软件项目而言，拥有高质量且及时更新的文档都是至关重要的。即使代码库写得很好、项目的核心理念创新且有用，糟糕的文档也可能导致项目的失败或被忽视。
编写良好的文档需要耗费相当多的时间和精力。因此，借助ChatGPT这样的大型语言模型(LLMs)来为你的项目和代码提供适当的文档，成为一种可行的替代方案。
使用ChatGPT为Python代码编写文档的一些好处包括：
- 提高生产力：它可以自动化与代码文档及其维护相关的任务，从而节省大量的时间和精力。
- 提高质量：它有助于确保你的文档准确、及时和全面。
- 提升用户体验：它可以生成引人入胜且用户友好的文档，为用户带来更好的体验。
- 降低成本：它帮助降低了文档创建和维护的成本。
- 提高合规性：它可以确保文档符合标准和法规，使其更加一致和专业。
通过使用ChatGPT，你可以快速为你的Python代码生成精美的文档。在接下来的章节中，你将学习如何将ChatGPT作为助手，为你的Python项目创建一致的docstrings和用户友好的外部文档的基础知识。
写docstrings时可能用到的ChatGPT提示词
在Python中，记录代码文档的主要方式是使用docstrings。在Python中，docstring通常是一个用三引号括起来的字符串，位于模块、函数、类和方法的第一行。Python会将这个字符串存储在名为.__doc__的属性中，以便对其进行特殊处理。
许多Python工具，包括代码编辑器和集成开发环境（IDE），会利用docstrings在您编写代码时提供实时帮助。而且，docstrings还是Python内置的帮助系统的一部分，您可以使用help()函数来获取相关帮助信息。
>>> help(str)
Help on class str in module builtins:
class str(object)
| str(object='') -> str
| str(bytes_or_buffer[, encoding[, errors]]) -> str
|
| Create a new string object from the given object. If encoding or
| errors is specified, then the object must expose a data buffer
| that will be decoded using the given encoding and error handler.
| Otherwise, returns the result of object.__str__() (if defined)
| or repr(object).
| encoding defaults to sys.getdefaultencoding().
| errors defaults to 'strict'.
|
| Methods defined here:
|
| __add__(self, value, /)
| Return self+value.
|
| __contains__(self, key, /)
| Return key in self.
...在这个示例中，你调用help()函数并传入str类作为参数，随后你将获得该类的文档页面，其中包含了该类的注释。
>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.在这种情况下，您可以通过直接访问str类上的.__doc__属性来获取类的注释。正如您可以得出的结论，注释为您的代码增加了很多价值。它们是您和其他Python开发人员用来了解任何Python对象的主要文档。
当您使用类似Sphinx或MkDocs的工具构建项目文档时，您还可以利用代码的注释。这些工具具有插件和功能，允许您提取注释并将其作为项目外部文档的一部分，这可以为您节省大量时间。
Python已经建立了编写良好注释的惯例。包、模块、类、方法和函数的注释都有具体的目标，并应遵循特定的指南。您可以在PEP 257中找到这些指南和约定。
尽管PEP 257提供了一个标准，但实际上在Python生态系统中，您会发现各种各样的注释风格。以下是一些常见的替代风格：
- Google风格注释：这种风格来自Google，您会在该公司的开源项目中找到许多示例。
- NumPy注释标准：这种风格是为NumPy库开发的，许多其他Python项目也采用了它。
- reStructuredText（RST）或Sphinx注释格式：这种风格基于reStructuredText，并来自Sphinx，这是一个用于自动化文档创建的有用工具。
- Epytext风格：这是一种轻量级标记语言，用于格式化注释，最初由Epydoc项目创建。每种风格都有自己的约定。通常，您应该选择一种风格，并在整个Python项目中一致使用。
在实践中，选择注释风格主要是个人偏好的问题。但是，您还应考虑项目的特定需求，包括以下特征：
- 项目的复杂性：如果您有一个庞大而复杂的项目，那么您可能会从Sphinx或NumPy风格中受益，因为它允许详细的文档。相比之下，小型项目可能只需要基本的文档，像PEP 257或Google风格的注释就足够了。
- 文档工具：如果您使用类似Sphinx或MkDocs的工具来生成项目的文档，那么应选择在您选择的工具中具有最佳支持的风格。
有了对Python注释的简要背景，您现在可以开始引导ChatGPT为您编写一些注释了。
将目标代码作为chatGPT提示词的一部分使用
创建编写注释提示的最快方法是将目标代码包含在提示本身的一部分。考虑以下示例，您创建了一个用于生成将两个数字相加的函数注释的提示，以下是您和ChatGPT可能的对话：
您：为以下函数编写一行注释：
def add(a, b):
return a + bChatGPT:
def add(a, b):
"""Return the sum of a and b."""
return a + b您：为以下函数编写Google风格的注释：
def add(a, b):
return a + bChatGPT:
def add(a, b):
"""Sum two numbers.
Args:
a (int or float): The first number.
b (int or float): The second number.
Returns:
int or float: The sum of the two numbers.
"""
return a + b您：为以下函数编写NumPy风格的注释：
def add(a, b):
return a + bChatGPT:
def add(a, b):
"""
Sum two numbers.
Parameters
----------
a : int or float
The first number to be added.
b : int or float
The second number to be added.
Returns
-------
int or float
The sum of a and b.
"""
return a + b您：为以下函数编写Sphinx风格的注释：
def add(a, b):
return a + bChatGPT:
def add(a, b):
"""
Calculate the sum of two numbers.
:param a: The first number.
:type a: int or float
:param b: The second number.
:type b: int or float
:return: The sum of the two numbers.
:rtype: int or float
"""
return a + b这三个注释看起来比您之前看到的单行注释更完整、更精细。当您添加关于要使用的特定风格的信息时，ChatGPT可以为您的函数生成完整的注释。当然，初始结果可能不是完美的，但这是一个很好的起点。
最重要的一点是，通过使用一个简短的句子作为提示，您已经获得了完整的注释。这对于您的项目是一个令人难以置信的生产力提升。
ChatGPT不仅允许您为函数生成注释，还可以处理模块、类等等。以下是一个生成Circle类及其方法注释的简短示例：
您：为以下类及其方法编写NumPy风格的注释：
class Circle:
def __init__(self, radius):
self.radius = radius
def calculate_area(self):
return round(math.pi * self.radius ** 2, 2)ChatGPT:
class Circle:
"""
A Circle class to perform some circle-related operations.
Parameters
----------
radius : float
The radius of the circle.
Attributes
----------
radius : float
The radius of the circle.
Methods
-------
calculate_area():
Calculates the area of the circle.
"""
def __init__(self, radius):
"""
Constructs all the necessary attributes for the circle object.
Parameters
----------
radius : float
The radius of the circle.
"""
self.radius = radius
def calculate_area(self):
"""
Calculate the area of the circle.
Returns
-------
float
The area of the circle rounded to 2 decimal places.
"""
return round(math.pi * self.radius ** 2, 2)哇！太棒了！通过一个简短的提示句子，您让ChatGPT为您的类及其所有方法生成了NumPy风格的注释。这是您代码库的一个很好的补充。
在提示词中仅包含签名
有时，您无法将目标代码作为提示的一部分。这可能是由于隐私要求，或者您只是想保护公司的代码安全。在这种情况下，您可以创建仅使用类、方法和函数签名的提示。
关于ChatGPT使用数据的问题目前有很多正在进行的诉讼。无论如何，您都应该检查ChatGPT的使用条款，以确保该工具适合您，并且您正在正确使用它。
要理解如何创建这些类型的提示，请考虑一个检查数字是否落在给定区间内的函数的签名：
您：为具有以下签名的函数编写Google风格的注释：
def in_interval(number, start, end):ChatGPT:
def in_interval(number, start, end):
"""
Checks if a given number is within a specified interval.
This function takes three arguments: a number, and the start
and end points of an interval.
It checks whether the given number falls within the specified
interval or not.
Args:
number (int or float): The number to check.
start (int or float): The starting point of the interval.
end (int or float): The ending point of the interval.
Returns:
bool: True if the given number falls within the interval,
False otherwise.
Raises:
ValueError: If the start is larger than the end, or if
the number, start, or end are not numbers.
"""在这个例子中，函数的签名是您提供给ChatGPT的唯一上下文。LLM足够智能，可以检查函数的名称和参数，并为您生成适当的注释。请注意，在这种类型的提示中，具有描述性的函数和参数名称至关重要。否则，输出可能不够好。
在大多数情况下，在函数的签名中添加类型提示将提高生成的注释的质量。
编写不使用代码的提示词
您还可以通过仅描述代码的输入和输出，或提供代码功能的详细描述来构建提示。同样，在不允许将代码作为提示的一部分上传时，这些类型的提示是有用的。
为了说明，以下是一个提示，要求ChatGPT为一个确定整数是否为质数的函数编写注释：
您：为一个接受整数作为参数并确定它是否为质数的函数编写Google风格的注释。
ChatGPT:
def is_prime_number(n):
"""
Determines if an input integer is a prime number.
This function takes an integer as an argument and checks
whether it is a prime number. A prime number is a
positive natural number greater than 1 that has no positive
integer divisors other than 1 and itself.
Args:
n (int): The integer to check.
Returns:
bool: True if the input integer is a prime number,
False otherwise.
Raises:
ValueError: If n is less than or equal to 1.
"""这个注释非常完整和有用。它甚至包括了质数的解释，这太棒了！您可以进一步调整并优化一些细节。然而，您已经有了一个很好的起点。
在提示词中询问测试和用例
使用示例可能是良好软件文档的最重要部分。通过代码示例，用户可以快速了解如何使用您的代码以及它的工作原理。通常，其他开发人员会浏览您的文档，直到找到一个代码示例。
因此，在您的注释中添加使用示例是一个大加分项。通过ChatGPT，提供使用示例只是在提示中包含一个简短句子的问题。考虑以下提示及其输出：
您：为以下函数编写NumPy风格的注释。添加一个包含使用示例的部分，作为doctest测试：
def add(a, b):
return a + bChatGPT:
def add(a, b):
"""
Add two numbers together.
This function takes two numbers (either integers or floats)
as arguments and returns their sum.
Parameters
----------
a : int or float
The first number to add.
b : int or float
The second number to add.
Returns
-------
int or float
The sum of the two input numbers.
Examples
--------
>>> add(1, 2)
3
>>> add(5.5, 2.5)
8.0
>>> add(100, -50)
50
"""
return a + b突出显示的行显示了函数的使用示例。在提示中，您指示ChatGPT使用doctest测试格式进行示例。这将提供两个重要的资产：
1、使用示例
2、对代码的基本测试
太棒了！您一举获得了两个好处！您的文档为用户提供了很酷的使用示例，同时还有帮助您使代码更健壮的测试。您可以使用doctest命令运行这些测试。
为您的Python代码创建外部文档
到目前为止，您已经使用ChatGPT帮助您为Python代码编写文档字符串。尽管文档字符串可能是项目文档的重要部分，但可能不足够。您的代码中可能有一些方面需要更深入的解释和详细的示例。
因此，如果您想要拥有改善用户与项目互动的优秀文档，那么您需要创建其他外部文档，例如README文件、教程和操作指南。
创建这种类型的文档将需要比为代码创建文档字符串更多的精力和时间。幸运的是，ChatGPT在这方面也可以帮助您。在接下来的几节中，您将探讨如何使用ChatGPT为Python项目创建外部文档的基础知识。首先，您将从README文件开始。
创建README文件
README文件可以说是您为任何Python项目创建的最基本的外部文档之一。您可能会找到许多有关在README文件中包含什么的不同建议。总的来说，该文件的内容将取决于您具体的项目及其主要目标。
在为给定项目创建README文件时，您可以依赖ChatGPT。如果您对在这种类型的文件中包含什么没有明确的想法，那么您可以询问ChatGPT：
您：编写README文件的推荐指南是什么？
ChatGPT：编写一个良好的README文件对于帮助用户了解您的项目的目的、如何使用以及如何潜在地为其做出贡献是很重要的。以下是一些通常包含在写得很好的README文件中的常见部分：
- 项目标题：README文件开头的简短、引人注目的标题。
- 项目描述：描述项目、它的功能以及它的目的的几段文字。
- 安装和入门：关于如何安装项目和任何依赖项，如何设置它以及如何运行它的详细说明。对于软件项目，包括必要的命令行。
- 使用示例：展示如何使用项目的示例。在这一部分，代码片段和截图可能非常有用。
- 贡献指南：如果您的项目是开源的，并且您接受贡献，请说明如何贡献和向项目提交拉取请求。您可能还包括代码风格偏好、他们应该通过的自动测试等等。
- 许可证：注明项目的许可证类型。
- 联系信息：提供您的联系信息或获取支持的指南。
- 致谢：在必要时，致谢相关工作或您使用的资源。
使您的README清晰、简洁且信息丰富。记住，通常这是人们访问您的项目时首次看到的东西，它可能极大地影响他们是否使用或为其做出贡献的决定。
当然，这个列表并不是完整或确定的。根据您具体的项目，您可能需要一些其他部分。然而，输出为创建一个出色的README文件提供了一个很好的起点。
现在，您可以选择文件的最佳结构，然后为ChatGPT创建特定的提示，以帮助您编写每个部分。首先从标题开始：
您：为一个提供基本数学运算的Python项目的README文件编写五个引人入胜的标题。
ChatGPT：
- “欢迎来到PyBasicMath：Python中基本数学运算的一站式解决方案”
- “PyBasicMath：使用基本数学函数简化复杂计算”
- “使用PyBasicMath轻松掌握数学：基本计算的完整Python包”
- “释放数学的力量：PyBasicMath快速高效的Python数学运算”
- “PyBasicMath：让数学变得易于接近，适用于各级别的Python开发者”
这是一份出色的标题建议清单。也许你已经对其中一些感兴趣，但你还可以从这些建议中挑选一些点子，自行创作一个引人入胜的标题。继续尝试编写提示，生成ChatGPT上方建议的其他部分，你将惊讶于ChatGPT在这方面的实用性。
作为练习，你可以尝试逐步编写具体的提示，以生成ChatGPT上建议的其他部分。
逐步向ChatGPT请求帮助逐段创建README文件，而不是一次性让它生成整个README文件，可能更加便捷有效，因为你可以调整提示，专注于特定部分。
生成代码解释
ChatGPT可以生成对代码工作原理的详细解释。这一功能为你创作外部文档提供了很好的机会。以下是一个提示，要求语言模型解释一个函数的运作方式：
你：解释以下函数的运作方式：
def find_extremes(iterable):
data = tuple(iterable)
if len(data) == 0:
raise ValueError("input iterable must not be empty")
return min(data), max(data)ChatGPT:
find_extremes(iterable)函数用于在可迭代对象（如列表、元组或任何其他Python可迭代对象）中查找最小和最大值。以下是逐步说明：
- data = tuple(iterable)：这行代码将输入的可迭代对象转换为元组。无论输入是列表、集合还是其他类型的可迭代对象，通过将其转换为元组，确保数据可以在接下来的步骤中一致地进行迭代。
- if len(data) == 0: raise ValueError("input iterable must not be empty")：如果元组数据的长度为零（即输入的可迭代对象为空），则引发一个带有消息“input iterable must not be empty”的ValueError异常。这充当守卫子句，防止函数处理空的可迭代对象，这将导致min和max函数也引发ValueError。
- return min(data), max(data)：这一行使用内置的Python函数min和max分别查找可迭代对象中的最小和最大值。这些值作为一个元组返回。
如果函数可以比较数据中的元素，则确定最小和最大值。如果不能（例如，可迭代对象是一个不实现比较操作的复杂对象），则min和max函数将引发TypeError。
总体而言，该函数接受任何可迭代对象，并返回一个表示可迭代对象中最小和最大值的元组。
ChatGPT的输出非常详细，逐行解释了函数的工作原理。这段解释将是项目外部文档的很好补充。你可以将这个解释用在教程、操作指南，甚至是README文件中，如果这适用于手头的项目。
创建用例示例
你已经了解到，ChatGPT可以作为文档字符串的一部分生成使用示例。它还可以生成你可以在教程、操作指南或README文件中使用的使用示例：
你：为以下函数编写三个使用示例。对每个示例进行解释：
def is_divisible(a, b):
if not a % b:
return True
return FalseChatGPT:
is_divisible(a, b)函数用于检查一个数字（a）是否能被另一个数字（b）整除。它使用模运算符（%），该运算符返回a除以b的余数。如果余数为0，则表示a能被b整除。
print(is_divisible(10, 5)) # Returns: True在这个示例中，该函数正在检查10是否能被5整除。由于10除以5的商为2，没有余数，所以函数返回True。
print(is_divisible(17, 3)) # Returns: False在这种情况下，该函数正在检查17是否能被3整除。由于17除以3的商为5，余数为2，所以函数返回False。
print(is_divisible(36, 9)) # Returns: True在这里，该函数检查36是否能被9整除。由于36除以9的商为4，没有余数，所以函数返回True。这表示36能被9整除。
请注意，你的提示包括你想要的具体示例数量。它还要求提供单独的解释。你还可以添加有关代码其他方面的更详细说明。例如，你可以询问特定的边缘情况，比如第二个参数为0时的情况。
详细的说明将提高生成的输出质量，并将解释引导到代码的具体和重要行为，这对你的用户可能非常有用。
编写教程和操作指南
既然你已经使用ChatGPT生成了代码解释和使用示例，你可以将它们组合起来，为你的代码开发教程或操作指南。
例如，假设你想创建一个关于使用一个执行基本数学计算的Python库的教程。如果你已经使用一个ChatGPT线程为该库生成了代码示例和解释，那么聊天已经有足够的上下文来生成标题建议、大纲、介绍，甚至是一个良好的结论。
以下是一个短提示，要求ChatGPT为教程生成一个大纲：
你：为一个执行基本数学计算的Python库的教程写一个大纲。
ChatGPT:
以下是一个基本数学计算的Python库教程的大纲：
I. 介绍
介绍Python中基本数学计算的重要性
引言Python的数学计算库的作用
提供教程的目标和预期受众
II. 安装与导入
安装数学计算库（例如，NumPy）
导入库到Python脚本或Jupyter Notebook
III. 基本数学操作
A. 算术运算
1. 加法
2. 减法
3. 乘法
4. 除法
5. 取余
B. 数学函数
1. 平方根
2. 指数函数
3. 对数函数
IV. 数组和矩阵操作
A. 数组基础
1. 创建数组
2. 访问和修改元素
3. 数组切片
B. 数组运算
1. 数组加法和减法
2. 数组乘法和除法
C. 线性代数操作
1. 矩阵乘法
2. 行列式和逆矩阵
V. 统计和随机数
A. 统计操作
1. 平均值
2. 中位数
3. 方差和标准差
B. 随机数生成
1. 生成随机数
2. 随机抽样
VI. 绘图与可视化
A. 使用Matplotlib进行基本绘图
1. 折线图
2. 散点图
B. 高级可视化（可选）
1. 热图
2. 3D图
VII. 案例研究
结合以上所学，通过一个实际案例演示如何应用数学计算库解决问题
VIII. 进阶主题（可选）
A. 优化和求解方程
1. 优化问题
2. 方程求解
IX. 总结
总结主要概念和技能
鼓励学习者进一步探索和应用所学知识
X. 参考文献
列出使用到的Python库和相关文档的引用
这个大纲可以根据目标受众的技能水平和需求进行调整。现在，您可以为ChatGPT编写具体的提示词，以生成每个部分的内容。您还可以在相应的部分插入使用示例和代码解释。试试看吧！
正如您所见，ChatGPT在记录Python项目方面是一个很好的伙伴。然而，在发布任何生成的内容之前，请确保对其进行全面的审查，以确保准确性和质量。
总结
现在，你知道如何利用像ChatGPT这样的工具来使用适当的文档字符串记录你的代码。你还学会了如何在ChatGPT的帮助下快速创建Python项目的外部文档。
在这个教程中，你学会了如何：
- 有效编写不同的ChatGPT提示以生成Python文档字符串
- 在使用ChatGPT生成文档字符串时采用不同的风格
- 要求ChatGPT为文档字符串添加doctest测试和使用示例
- 使用ChatGPT构建Python项目的外部文档
有了这些技能，你现在可以开始为你的Python代码和项目创建有用且引人入胜的文档。