Python 文档最佳实践

Python 是一种非常棒的编程语言，适用于经验不足和经验丰富的程序员。如果我们刚刚开始，请查看这 10 个 Python 文档的最佳实践。

任何软件开发方法都必须有文档。它可以用于创建代码示例和教程，并且有助于开发人员和用户理解代码。

Python 文档的盛誉是实至名归的。Python 社区非常努力地创建用户友好且质量最高的文档。

为了确保他们的 Python 文档尽可能好，开发人员仍然应该遵循一些最佳实践。本教程将介绍其中十个推荐的实践。

1. 描述我们的代码。

代码是一种宝贵的资源。它是我们劳动的成果，体现了我们的独创性和思想。当我们为代码编写文档时，我们不仅仅是为将来参考而保存我们的工作，还在记录我们的想法和思想。如果您以后需要重新审视我们的代码，或者需要向其他人解释，这份文档会非常有帮助。

如果我们的代码有文档，也更容易维护和增强。当我们的文档精确而直接时，更容易识别错误和需要改进的地方。此外，文档有助于加快问题的检测和纠正。

最后，编写代码有助于提高我们的编程技能。当我们花时间记录代码时，我们被迫以不同的方式思考代码。我们必须考虑如何将我们的代码传达给其他人。这可能有助于我们解决代码中的问题。

2. 采用统一的风格

当多人为项目做出贡献时，代码必须看起来像是由一个人开发的。这是为了使代码更易于阅读和理解。它还使查找和修复错误更简单。此外，采用一致的风格更容易自动生成文档。例如，Sphinx 程序可以从 Python docstring 生成文档。如果 docstring 以标准化的方式编写，生成的文档将更易于阅读。

尽管有许多其他方法可以生成 Python docstring，但 Google Python 风格指南是使用最广泛的模型。本手册提供了关于如何生成简短清晰的文档以及如何格式化 docstring 的建议。

3. 为所有公共类、方法、函数和模块创建 docstring。

当尝试理解我们的代码时，人们会首先查看我们的 docstring。它们应该以清晰、简洁的方式解释我们的代码的作用以及如何使用它。

如果我们不为我们的公共模块、函数、类和方法添加 docstring，人们将难以理解我们的代码，甚至可能会放弃。

使用 docstring 记录我们自己的代码将帮助我们将来回忆起它的作用。几天或几周后，我们很容易忘记我们在创建代码时正在做什么。

但是，如果我们的 docstring 编写得很好，我们可以轻松地提醒自己我们的代码做了什么。

最后，创建 docstring 是一种熟悉 Python 文档规范的有用方法。如果遵循这些规范，我们的代码将更易于他人阅读和理解。

4. 在文档中加入插图

人们在学习如何使用新模块或函数时，常常希望看到一个示例。他们对如何在自己的代码中使用模块或函数以及它完成了什么有了更好的理解。

如果我们的文档中不提供示例，人们将不得不去其他地方（例如在源代码中）查找，这可能既耗时又令人沮丧。此外，如果用户找不到任何示例，他们可能会决定根本不使用我们的模块或函数。

因此，在我们的 Python 文档中包含至少一两个示例至关重要，最好附带对每个示例作用的描述。这可以大大提高用户对我们的模块或函数的理解，并增加他们使用它的可能性。

5. 维护更新日志。

更新日志是一个文件，其中包含按时间顺序组织的、为项目的每个版本精心策划的重要更改列表。这适用于对 Python 项目进行的任何实质性或值得注意的修改，例如新功能、错误修复、破坏性更改和其他更改。

开发人员（以及其他利益相关者）可以更好地理解版本之间的变化，这得益于更新日志，更新日志还有助于解释为什么进行了这些更改。为了保持向后兼容性并选择何时以及如何升级到新版本，这种理解至关重要。维护更新日志还使人们更容易为项目做出贡献，因为他们立即理解必须做什么以及为什么。

更新日志可以以多种方式格式化，但最关键的因素是确保它易于阅读和理解。实现这一点的最简单方法是坚持标准结构并编写简洁、直接的条目。

6. 描述局限性

如果您正在记录一个 Python 项目，某人可能希望以我们不打算的方式使用我们的代码。如果他们这样做，他们就会遇到困难。

如果我们事先明确指出代码的限制，人们可以节省大量时间和挫败感。此外，我们可以避免听到关于我们的代码的负面评价。

那么，我们如何描述代码施加的限制呢？

识别这些限制是第一步。尽管这可能具有挑战性，但我们必须尽可能真实和公正。

一旦我们确定了限制，下一步就是记录它们。包括以下内容：

对限制、其理由以及规避它的方法的详细解释。

通过遵循这些说明，我们可以确保我们的 Python 文档清晰有用，并且它为代码用户设定了合理的期望。

7. 不要记录内部信息

当我们记录内部信息时，我们只生成对熟悉我们代码的人有用的文档。新用户不会从中受益，甚至可能会感到困惑。

类、函数和变量的名称是内部信息的示例。这些详细信息无需在文档中提供，因为那些以前熟悉我们的代码的人已经知道它们。

内部信息只有在有不寻常或可能被误解的地方才应该被记录。例如，我们可能希望列出由名为“get user”的函数返回的字典中存在的键，该函数提供用户信息。即使如此，我们也应该只在确实必要时才采取此行动。

8. 使用 Sphinx 创建有吸引力的文档。

Georg Brandl 开发了 Sphinx，这是一个可以轻松生成智能且精美文档的工具。它以 BSD 许可证提供。它最初是为 Python 手册开发的，此后许多其他项目都采用了它。

Sphinx 使用的标记语言是 reStructuredText，它的许多功能都是专门为 Python 文档创建的。例如，它可以自动从 Python 源代码构建 API 文档，并允许从 Python 模块添加 docstring。

Sphinx 的许多功能也使其易于生成有吸引力的文档。例如，它可以直接从 reStructuredText 源生成 PDF 页面，并且允许使用 LaTeX 进行数学公式。

9. 将我们的记录在线存储

当我们的文档托管在线时，人们可以更容易地找到和浏览它。如果我们的文档存储在 GitHub 等知名平台上，人们甚至可以加星或 fork 我们的存储库，这增加了其他人找到它的可能性。

此外，通过在线托管我们的文档，我们可以受益于搜索引擎优化 (SEO) 等功能。通过为适当的关键字优化文档，当用户搜索与我们描述的主题相关的内容时，我们可以大大简化他们查找文档的过程。

最后，将我们的文档在线托管使其更容易保持最新状态。当我们的文档在一个中心区域时，进行更新和添加比必须更新散布在互联网上的多个版本的文档要容易得多。

10. 确保我们所有的文档都是最新的。

我们的文档将随着代码库的演变而演变。如果我们不跟上代码，我们的文档很快就会过时和错误。在使用我们的代码时，这可能会导致新手和经验丰富的开发人员感到困惑和沮丧。