拒绝996低效率：ChatGPT助你轻松搞定代码注释和文档-CSDN博客

本文链接：https://blog.csdn.net/bf02jgtrs00xktcx/article/details/134453416

良好的注释对于任何成功的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生态系统中，您会发现各种各样的注释风格。以下是一些常见的替代风格：