记录 Python 代码：完整指南

一、概述

在本文中，您将了解记录代码的重要性、注释和记录代码的差异、使用文档字符串记录 Python 代码库，以及记录 Python 项目的方法。

代码文档可以帮助理解代码、提高协作效率和可维护性。注释是对单行代码解释，而记录代码详细描述整个代码段。文档字符串用于说明代码库，应包含目的、参数、返回值和示例等信息。

记录 Python 项目的方法包括命名约定、目录结构、README文件和添加注释、记录代码和文档字符串。

希望这能帮助您更好地记录和管理 Python 项目。

二、 为什么记录代码如此重要

在这篇文章中，我们将探讨记录 Python 代码的重要性。Python 的创建者Guido van Rossum曾经说过：“代码被阅读的频率高于编写代码”。这句话观察到了一个很有意思的事实，那就是当我们编写代码时，我们实际上是在为两个不同的受众编写代码：用户和开发人员，包括自己。

这两个受众都非常重要。如果我们回顾我们之前编写的旧代码，对其产生困惑，那么想象一下其他人在阅读同样的代码时会有何感受。

然而，这种观点存在着两个方面。想象一下你在网上找到一个看起来绝对棒的图书馆。开始使用它之后，你可能需要示例、发行说明、文章等指导文档，告诉你如何使用它完成你最初认为它可以完美完成的任务。但在搜索一段时间后，你可能会发现文档并不存在或者无法使用。

这可能会让人感到沮丧，并阻止你充分利用这个库，无论它有多好。正如丹尼尔·普罗奇达所总结的那样："你的软件有多好并不重要，因为如果文档不够好，人们就不会使用它。“如果一个 Python 库没有被使用，那么它真的有用吗？

展望未来，本指南将向您展示如何正确记录您的 Python 代码，无论是一个简短的 10 行脚本还是一个复杂的 10，000 行库。通过正确记录代码，我们可以帮助防止潜在用户遇到沮丧的感觉。

请继续阅读下一篇文章，开始探索注释和记录代码的相关内容。

三、 记录与注释代码

在编写代码时，准确记录和注释代码是至关重要的。它不仅可以帮助他人理解你的代码，还能提高协作效率和可维护性。在开始记录代码之前，我们首先需要明确文档和注释的区别。

注释主要用于描述代码，为其他开发人员提供更好的理解。它们对于那些需要进一步开发和维护代码的人来说非常有价值。注释与良好的代码结合使用，可以引导读者更好地理解代码的目的和设计。正如杰夫·阿特伍德所说：“代码告诉你怎么做；注释告诉你为什么这样做。”注释是代码中的重要补充，它们提供了关键的上下文信息。

然而，记录代码则是向用户描述其用法和功能。记录代码的目标受众主要是代码的潜在和实际用户。它们提供了关于如何正确使用代码、预期输出和一些示例等信息。通过将这些细节明确地记录下来，我们可以使用户更轻松地理解和利用代码。

现在让我们来看看在何时以及如何注释代码。在 Python 中，使用（#）或哈希符号开始的行被视为注释。注释应该简洁明了，不超过几句话。让我们来看一个示例，在一个简单的打印语句之前有一个注释，它以#一个简单的注释开头。

这里需要注意的是，注释会在编辑器中以不同的颜色显示，以示区分，这样可以清楚地表明它是注释而不是函数或其他代码。

根据 PEP 8（Python 代码布局的标准准则），注释的长度不应超过 72 个字符，即使你的项目将最大行长度设为超过建议的 80 个字符，也应该保持注释的限制在 72 个字符以内。如果注释的内容长度超出字符限制，可以适当地将其拆分为多行注释。在下面的示例中，你可以看到注释跨越两行，每行都以哈希符号开头。

通过良好的记录和注释，你可以提高代码的可读性、可维护性和可理解性。它们对于团队合作开发和长期项目的管理非常重要。所以在编写 Python 代码时，请务必养成良好的记录与注释的习惯，这将使你的代码更加易于理解和使用。

注释代码有多种用途。其中包括规划和审查新的代码段，因为首先使用注释作为概述该代码部分的目的和功能的方式可能是合适的。

算法描述。在这种情况下，使用注释可用于解释算法的工作原理或如何在代码中实现算法。描述为什么采取某种方法而不是另一种方法也可能是合适的。

这是一种方便的方法，用于标记已知问题所在的某些代码段，或者可以进行改进的地方。一些例子是#BUG，#FIXME和#TODO。

应遵循以下四条基本规则来注释代码：

1. 使注释尽可能靠近它们描述的代码。当注释不在他们描述的代码附近时，这可能会让读者感到沮丧，并且在进行更新时会错过。
2. 不要使用复杂的格式，如表格或ASCII数字。随着时间的推移，复杂的格式可能难以维护，还可能导致读者分心。
3. 不要包含冗余信息。假设读者掌握了基本的编程原理和编码语法。
4. 将代码设计为自解释代码。理解代码的最简单方法是阅读代码。当您的代码设计使用清晰、易于理解的概念时，读者将能够快速概念化您的意图。

注释的最后一个方面是类型提示。类型提示在3.5版本中添加到Python中。它是一种帮助代码读者的附加形式，并将前面提到的第四条规则提升到一个新的级别。通过使用类型提示，开发人员可以设计和解释其代码的某些部分，而无需以传统方式进行注释。

请记住，注释旨在为读者提供帮助，通过理解软件的目的和设计来指导自己。然而，使用类型提示可能需要额外的工作来创建或更新项目文档。

四、 使用文档字符串进行文档记录（第 1 部分）

在Python中使用文档字符串记录代码非常重要。文档字符串是内置的字符串，用于帮助记录项目并提供给用户查看。可以通过help()函数结合文档字符串来打印对象的说明。下面是一个例子：

# 将字符串发送到help()函数
help(str)

这将提供大量关于字符串的信息。其中，我们主要关注的是第一部分，它准确地描述了字符串的作用：从给定的对象创建一个新的字符串对象。

要查看特定输出是如何生成的，可以使用dir()命令检查对象的属性。例如，对于字符串对象str，我们可以使用dir(str)来检查其属性。其中，我们特别关注__doc__属性，通过将.__doc__属性发送到print()命令进行进一步检查，可以得到与help()函数结果的第一段相同的文本。

需要注意的是，对于内置对象（如str），不能操作. __doc__属性，否则会引发回溯错误。但对于其他自定义对象，可以直接访问和操作文档字符串属性。

在Python中，我们可以创建自己的函数，并为其添加文档字符串，以提供函数的简要说明和使用方法。下面是一个例子：

def say_hello():
    """这个函数用于向用户打招呼并确认是否找到了正确的函数。"""
    print("你好<不管你叫什么名字>，你要找的是我吗？")

上述代码定义了一个名为say_hello()的函数，并使用三重双引号创建了一个文档字符串。文档字符串描述了函数的用途和功能。

通过定义文档字符串，我们可以更方便地了解和使用这个函数。当其他人或我们自己使用函数时，可以通过调用help()函数或者查看.__doc__属性来获取函数的文档字符串。

例如，我们可以这样使用文档字符串：

>>> help(say_hello)

这将显示如下内容：

Help on function say_hello in module __main__:

say_hello()
    这个函数用于向用户打招呼并确认是否找到了正确的函数。

在文档字符串中，我们应该包含函数的摘要、使用方法和其他必要的说明。同时，遵循PEP 257的约定，使用三重双引号作为文档字符串的起始和结束符号，并保持每行最大字符长度不超过72个字符。

通过良好的文档字符串规范，我们能够更好地理解和使用自定义函数，提高代码的可读性和可维护性。

当编写文档字符串时，我们需要注意一些格式设置规范。以下是一个示例：

def my_function():
    """
    这是一个示例函数的文档字符串。

    示例函数的作用是...

    示例使用方法：
    1. ...
    2. ...
    3. ...

    注意事项：
    - ...
    - ...
    """

    # 函数的代码实现
    pass

在这个示例中，我们使用了三重双引号来创建文档字符串，并在起始和结束处各留出一行空白。接着是一个简要的摘要描述函数的作用和功能。下面是示例的使用方法和一些注意事项。

在编写文档字符串时，遵循以下几点是很重要的：

• 使用三重双引号作为起始和结束符号。
• 在起始和结束的三重双引号之后、函数定义之前添加一个空行。
• 摘要部分应该清楚地描述函数的作用和功能。
• 使用列表或编号的方式提供示例使用方法。
• 提供任何必要的注意事项、参数说明或返回值说明。

通过遵守这些格式设置规范，我们可以创建清晰、易读的文档字符串，帮助其他人更好地了解和使用我们的代码。

在Python中，使用文档字符串为函数添加说明和使用方法非常有帮助。通过定义良好格式的文档字符串，我们可以使代码更可读、理解和维护。

文档字符串应该包含函数的摘要、使用方法和其他必要的说明，遵循PEP 257的约定，并保持每行最大字符长度不超过72个字符。

在使用Python的help()函数或查看.__doc__属性时，文档字符串将提供有关函数的详细信息。因此，良好的文档字符串规范是编写高质量代码的重要组成部分。

五、 使用文档字符串进行文档记录（第 2 部分）

现在让我们深入探索一下。我们从类文档字符串开始示例。如您所见，它非常简单。只需将字符串文本直接放在类或类方法的下方，具体取决于编写文档字符串的目的。

这就是基本的文档字符串。类文档字符串是为类及其任何类方法创建的。文档字符串位于类或类方法之后且相对于它们缩进一个级别，就像前面的示例一样。

类文档字符串应包含以下信息：类的用途和行为的简要摘要、任何公共方法及其简要说明、所有类属性和实例属性以及与子类接口相关的内容（如果类被设计为可被子类化）。

类构造函数参数应记录在.__init__()类方法的文档字符串中。每个方法应使用独立的文档字符串进行记录。类方法的文档字符串应包括以下内容：方法是什么以及它的用途的简要说明；传递的任何参数（包括必需参数和可选参数，包括关键字参数）；标记任何被视为可选或具有默认值的参数；执行方法时可能发生的任何副作用；引发的任何异常；以及对方法调用的任何限制。

现在我们来看一个例子。这个数据类表示动物。它包含一些类属性、实例属性、.__init__()方法和单个实例方法。

如果我们逐个查看它们，你会发现以下内容。

你可以看到文档字符串以三重双引号（"""）开始，这表明它是一个多行文档字符串。它解释了每个属性-它是什么以及每个属性的简短描述。

每个方法也有自己的文档字符串。

在.__init__()方法中，您可以看到它有自己的文档字符串，和之前提到的相同。如果我们继续往下看，在底部你会看到如果动物没有声音会引发错误的说明，这是在文档字符串中特别注明的，如前所述。

让我们继续讨论包和模块文档字符串。包文档字符串应该放置在包的__init__.py文件的顶部。

模块和脚本的文档字符串是在编写代码时非常重要的信息资源。在模块中，文档字符串应包含对模块及其用途的说明，以及导出的类、异常、函数和其他对象的列表。此外，函数的文档字符串应提供对函数功能、参数、副作用、可能引发的异常以及何时可以调用该函数的简要描述。

对于脚本来说，文档字符串位于文件的顶部，应记录得足够详细，以便用户能够全面了解如何使用脚本。它可以介绍脚本的目标、假设条件和必需的第三方包。如果使用argparse库进行命令行解析，则可以通过
argparse.parser.add_argument()函数的help参数来省略特定参数的文档说明。

下面是一个提取电子表格列标题的脚本示例。它简要描述了脚本的功能和使用要求，同时指出需要安装pandas库。

在编写Python代码时，文档字符串是一个十分重要的元素。它通常位于函数或方法的开头，并提供有关该函数或方法的说明。

文档字符串的格式可以采用不同的方式。一种常见的格式是NumPy/SciPy样式的文档字符串，也可以使用谷歌文档字符串格式或Epytext格式。

NumPy/SciPy文档字符串结合了谷歌文档字符串和重新结构化文本的特点。它包含参数、返回值和属性的说明，以及其他与函数或方法相关的信息。

谷歌文档字符串是谷歌推荐的文档格式之一，布局与NumPy/SciPy文档字符串类似，但略有不同。

Epytext是Epydoc的Python版本，它借鉴了Java的风格。在Epytext中，每个类型和参数前面都有“at”（@）符号。

选择适合自己的文档字符串格式完全取决于个人偏好，但一旦选择后，应在整个项目中保持一致性。

六、 记录你的 Python 项目（第 1 部分）

Python项目的形状和大小可以各不相同，并且可用于多种目的。相应地，项目文档也会因此而有所不同，它应该适合具体情况。要记住项目的用户是谁以及他们的需求，在文档中作出相应的调整是很重要的。

根据项目类型的不同，建议使用文档的一些方面。总体上，项目可以分为私有项目、共享项目和公共/开源项目。首先，我们来看私有项目。私有项目只供作者自己使用，通常不会发布给其他用户或开发人员使用。对于这类项目，文档可能不需要非常全面，但以下是一些建议的内容：

1. README文件：提供项目及其用途的简要摘要，并包括安装或操作项目的任何特殊要求。
2. examples.py：一个Python脚本文件，提供了使用该项目的简单示例。

即使是私有项目，你仍然要考虑自己作为用户时可能会找到哪些内容令人困惑，并在注释、文档字符串或README文件中记录下来。

接下来是共享项目。这些项目是编写者与少数其他人进行合作的项目。虽然项目的主要用户仍然是作者自己，但现在还包括几个其他团队成员。针对这类项目，建议的文档应该比私有项目更严谨，主要是为了帮助新成员迅速熟悉项目进展或提醒贡献者和用户项目的新变化。

对于共享项目，建议在文档中添加以下内容：

1. README文件：提供项目及其目的的简要摘要，并包括安装或操作项目的任何特殊要求。
2. examples.py：一个Python脚本文件，提供了使用该项目的简单示例。
3. 如何做出贡献：包括介绍如何给项目作出贡献的说明，以便新的贡献者了解如何参与项目。

以上是关于私有项目和共享项目的一些建议，希望能帮助你整理Python项目文档。根据具体情况，你可以根据自己的需求进行相应调整。

公共和开源项目旨在与更广泛的社区共享，并可能涉及大型开发团队。为了确保项目的顺利进行，以下是建议应添加到项目中的一些部分。

首先，自述文件是必不可少的，其中应包括对项目及其目的的简要摘要。概述项目的功能、目标和与之前版本相比的重大更改，并提供安装或操作该项目的特殊要求。此外，自述文件还应包含指向更多文档、错误报告和其他重要信息的链接。

其次，如何贡献部分应明确指导新贡献者加入项目并提供具体步骤和方法。解释他们可以开发的新功能、修复的已知问题、应添加的更多文档以及测试或报告问题的方式。

此外，行为准则文件定义了开发者在开发或使用该软件时应遵守的行为规范。它明确了对待彼此的方式，并说明如果代码被破坏将会采取何种措施。许可证文件描述了项目使用的许可证类型。

最后，还应包含一个名为"docs/"的文件夹，其中提供更多文档资源，如使用手册、API文档和示例代码等。

通过重视项目文件，并按照以上建议添加适当的部分，可以提高公共和开源项目的可用性和可维护性，促进更广泛的社区参与和贡献。

七、 记录你的 Python 项目（第 2 部分）

在2017年的PyCon上，Daniele Procida发表了一篇关于记录Python项目的演讲和随后的博客文章。他提到所有项目都应该有以下四个主要部分，以帮助您集中精力。

首先是教程，它是通过一系列步骤来完成项目或有意义的练习的课程。它通常面向用户的学习。

其次是操作指南，它是引导读者完成解决常见问题所需步骤的指南。可以将它们视为面向问题的食谱。

接下来是参考文献，它澄清和阐明特定主题的解释，面向用户理解。最后是解释，它是对机器及其操作方式的技术描述，包括关键类、函数、API等。可以将其想象成一篇百科全书式的文章。

这个方便的表格展示了这四个部分如何相互关联以及它们的总体用途。教程和解释在学习时都是最有用的，但它们的不同之处在于教程是实用的，解释是理论性的。操作指南和参考遵循相同的思想，即操作指南是实用的，参考是理论性的，但它们在编码时更有用，而不是在学习时。通过以这种方式组织项目，您将能够以用户可以轻松导航的格式回答问题。

此外，在记录代码时可能会遇到困难，但有一些工具和参考资料可以帮助您入门，如Sphinx、Epydoc、Read the Docs、Doxygen、MkDocs和Pycco等。除了这些工具，还提供了其他教程、视频和文章作为补充资源。

当您不知道文档下一步应该去哪里时，可以使用文档进展的方法。例如，如果没有任何文档，从零开始；如果已经有一些文档，但缺少关键方面的说明，先填补这些空缺。记住，不要因编写所需的工作量而气馁或感到无所适从。一旦开始，继续就变得更容易了。如果遇到问题，可以私信我，我会尽量帮助大家。