英文参考文献作者姓名格式-编写更多Pythonic代码（8）——记录Python代码：完整指南

一、概述

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

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

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

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

2. 为什么记录代码如此重要

在本文中，我们将探讨记录 Python 代码的重要性。 Python 的创建者 Guido van Rossum 曾经说过：“代码读的次数多于写的次数”。 这句话观察到了一个非常有趣的事实，当我们编写代码时，我们实际上是在为两个不同的受众编写代码：用户和开发人员，包括我们自己。

双方观众都非常重要。 如果我们回顾之前编写的旧代码并对其感到困惑，想象一下其他人在阅读相同代码时会有什么感受。

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

这可能会令人沮丧，并阻止您充分利用图书馆，无论它有多好。 正如 Daniel Procida 总结的那样：“无论你的软件有多好，因为如果文档不够好，人们就不会使用它。” Python 库如果不使用真的有用吗？

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

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

3.记录并注释代码

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

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

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

现在让我们看看何时以及如何注释代码。 在 Python 中，以 (#) 或井号符号开头的行被视为注释。 评论应该简短、简洁，不超过几句话。 让我们看一个示例，其中在以 #a simple comment 开头的简单 print 语句之前有一个注释。

这里需要注意的是英文参考文献作者姓名格式，注释在编辑器中会以不同的颜色显示来区分，这样可以清楚地表明它们是注释而不是函数或其他代码。

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

有了良好的文档和注释，您可以提高代码的可读性、可维护性和可理解性。 它们对于团队发展和长期项目的管理非常重要。 所以在编写Python代码时，请一定要养成记录和注释的好习惯，这会让你的代码更容易理解和使用。

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

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

这是一种标记已知问题所在或可以改进的某些代码部分的便捷方法。 一些例子是#BUG、#FIXME 和#TODO。

代码注释应遵循四个基本规则：

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

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

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

4. 带有文档字符串的文档（第 1 部分）

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

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

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

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

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

在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__属性时，文档字符串将提供有关该函数的详细信息。 因此，良好的文档字符串约定是编写高质量代码的重要组成部分。

5. 带有文档字符串的文档（第 2 部分）

现在让我们更深入地挖掘一下。 我们以类文档字符串开始示例。 正如您所看到的，这非常简单。 只需将字符串文字直接放在类或类方法下方，具体取决于编写文档字符串的目的。

这是基本的文档字符串。 为该类及其任何类方法创建一个类文档字符串。 文档字符串放置在类或类方法之后，并相对于它们缩进一级，如前面的示例所示。

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

类构造函数参数应记录在 .__init__() 类方法的文档字符串中。 每个方法都应该用它自己的文档字符串来记录。 类方法的文档字符串应包括以下内容： 该方法是什么及其用途的简要描述； 传递的任何参数（必需的和可选的，包括关键字参数）； 标记任何被认为是可选的或具有默认值的参数； 执行该方法时可能发生的任何副作用； 提出的任何例外情况； 以及对方法调用的任何限制。

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

如果我们一一查看，您会发现以下内容。

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

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

在 .__init__() 方法中，您可以看到它有自己的文档字符串，与前面提到的相同。 如果我们继续往下看，在底部你会看到一条声明，如果动物没有声音，就会引发错误，正如前面提到的，文档字符串中特别指出了这一点。

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

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

对于脚本，文档字符串位于文件顶部，并且应记录足够详细的信息，以便用户完全了解如何使用脚本。 它描述了脚本的目标、假设和所需的第三方包。 如果使用 argparse 库进行命令行解析，则可以通过 argparse.parser.add_argument() 函数的 help 参数省略特定参数的文档。

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

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

文档字符串可以采用不同的方式进行格式化。 常见的格式是 NumPy/SciPy 风格的文档字符串，但也可以使用 Google 文档字符串或 Epytext。

NumPy/SciPy 文档字符串结合了 Google 文档字符串和重构文本的功能。 它包含参数、返回值和属性的描述，以及与函数或方法相关的其他信息。

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

Epytext 是 Epydoc 的 Python 版本英文参考文献作者姓名格式，它借鉴了 Java 的风格。 在 Epytext 中，每个类型和参数前面都有“at”(@) 符号。

选择适合您的文档字符串格式完全取决于个人喜好，但一旦您选择，它应该在您的项目中保持一致。

6. 记录您的 Python 项目（第 1 部分）

Python 项目可以有各种形状和大小，并有多种用途。 因此，项目文档也会相应变化，并且应该适合具体情况。 重要的是要记住项目的用户是谁以及他们的需求是什么，并在文档中进行相应的调整。

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

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

即使对于私有项目，您仍然需要考虑作为用户可能会感到困惑的内容，并将其记录在注释、文档字符串或自述文件中。

接下来是共享项目。 这些项目是作者与其他一些人合作的项目。 虽然该项目的主要用户仍然是作者本人，但现在还包括其他几位团队成员。 对于此类项目，推荐的文档应该比私有项目更加严谨，主要是为了帮助新成员快速熟悉项目进展或者提醒贡献者和用户项目的新变化。

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

自述文件：提供项目及其用途的简要摘要，并包括安装或操作项目的任何特殊要求。 example.py：Python 脚本文件，提供使用该项目的简单示例。 如何贡献：包括有关如何为项目做出贡献的说明，以便新贡献者知道如何参与。

以上是关于私有项目和共享项目的一些建议，希望对大家整理Python项目文档有所帮助。 根据情况，您可以根据自己的需要进行相应调整。

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

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

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

此外，行为准则文档定义了开发人员在开发或使用软件时应遵循的行为准则。 它阐明了如何对待彼此，并解释了如果代码被破坏该怎么办。 许可证文件描述了项目使用的许可证类型。

最后，还应该有一个名为“docs/”的文件夹，它提供了更多的文档资源，例如用户手册、API文档和示例代码。

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

7. 记录您的 Python 项目（第 2 部分）

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

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

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

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

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

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

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