如何编写代码文档：示例、类型、最佳实践和工具

每个开发人员都曾经历过这种情况 — 盯着他们几个月前编写的代码库，努力回忆某些决策背后的原因或不同组件是如何组合在一起的)。没有什么比后来看着自己的代码却不记得它是做什么的或者它如何工作更糟糕的事情了。

另一种常见的情况是，当新同事加入项目并且无法理解代码时，因为之前的开发人员认为这些代码的含义已经足够明显了。

这些场景都是再熟悉不过的，它们突显了一个经常被忽视的编程关键部分：代码文档。仅仅编写有史以来最美的代码是不够的。你也应该解释它。

在本文中，我们将探讨代码文档的重要性、类型、遵循的最佳实践、代码文档工具等等。让我们深入探讨。

什么是代码文档？

代码文档是创建描述和注释的过程，这些描述和注释解释了一段代码的工作原理、作用以及如何使用它。

这些解释弥合了代码本身与与之交互的人类之间的鸿沟。用代码文档的利益相关者包括：

软件开发人员 — 例如，您未来的自己和同事在同一个代码库上协作，未来的代码维护者，以及新的团队成员;
需要了解项目结构、确定其进度、评估技术债务和规划未来发展的项目经理;
利用代码文档了解软件产品的预期行为，并测试典型场景和边缘案例的质量保障团队成员;
利用代码文档创建用户手册和其他类型的技术文档的技术作家

代码文档提供了几个好处，包括清晰度、更容易的可维护性、团队成员之间更好的协作以及为新员工改进的开发人员入职培训。

代码文档与作为代码的文档

虽然它们听起来很相似，但代码文档与作为代码的文档（docs-as-code）不是同一回事。代码文档是在代码内部直接编写解释的实践，或者在单独的文件中帮助开发人员理解它的工作方式和使用方法。

另一方面，docs-as-code 是一种涉及使用与编写代码相同的工具和流程创建和管理文档的方法。这包括：

版本控制系统，用于存放源文件、跟踪更改和存储不同种类的文档;
用于查找拼写和语法错误、断开链接、样式违规等的自动化测试工具;
用于生成、更新和部署文档的 CI/CD 工具。

Docs-as-code 确保所有类型的软件始终是最新的、版本化的，并与它所描述的项目一起进行维护。该方法涵盖代码文档，但不限于此。

代码文档类型

代码文档可以是内部的，这意味着它位于代码库本身内部，或者以单独文件的形式位于外部。前一种类型也称为源代码文档，分为两大类

代码注释，以及
文档注释或字符串（如 Python 中的文档字符串），可由文档生成器解析并转换为 HTML、PDF 或其他格式的文档。

它们可以是单行或多行，后者用于提供额外的上下文或解释复杂的部分。单行注释通常不能超过 80 个字符。

这两个组都提高了代码的可读性、清晰度和可维护性，但服务于不同的目的)。每种编程语言都有自己的注释和文档字符串语法。

外部代码文档通常是描述如何实现、运行和配置代码及其预期输出的 README 文件。

API 文档有时也称为代码文档。我们的另一篇文章《如何编写API文档》对此进行了更详细的解释)在这篇文章中，我们将重点介绍其他种类的代码描述。

代码注释

代码注释（也称为内联注释）是描述代码行或代码块的含义或作用的简短说明。它们仅存在于源代码文件中，对编译器和浏览器不可见。下图显示了一段 JavaScript 代码的注释示例。

何时使用它们

代码注释对于解释不明显的事情很有用，例如

代码块的高级用途，
新颖或复杂的算法，
为什么选择特定的（可能不理想的）解决方案，以及其他实施决策;和
TODO 和 FIXME 注释，以提醒必须更改或改进的内容。

您还可以使用注释语法在调试或开发期间暂时禁用代码段，以便快速测试和迭代，正如您所记得的)，编译不会看到标记为注释的行。

如何编写代码注释

让我们讨论一些在代码中编写清晰有用的注释的最佳实践。

编写自文档化代码。最好的代码是自文档化的——也就是说，它如此清晰和表达力强，几乎不需要注释进行额外的解释。下图是一个可能难以理解的代码示例。

下图是自文档化代码的示例：函数和变量名称清楚地传达了它们的含义和用途。

确保您的注释清晰易懂。撰写简洁、清晰且易于理解的注释。除非必要并且在你的领域中广为人知，否则避免使用行话。下图是一个模糊且无用的代码注释示例。

下图是详细注释的示例：它们解释了代码的作用，甚至提供了正在使用的公式。

解释原因。虽然记录代码的作用和方式很重要，但解释做出某些决定的原因可以为未来的开发人员（包括未来的自己）提供有价值的背景信息。给出架构选择、算法选择，甚至是可能不明显的具体代码行背后的原因。

下面的图片中的注释没有解释为什么使用快速排序算法。它只是陈述了代码的功能，这已经是显而易见的了。

相比之下，下图中的注释正确解释了开发人员选择快速排序算法的原因。

链接到外部代码的原始源代码。 在将来自外部源的代码添加到项目时，提供链接非常重要。这种做法不仅给予原作者以认可，还有助于其他人理解上下文并在需要时找到更多信息。包括源链接可以确保透明度并帮助维护代码库的完整性。

文档字符串或文档注释

文档注释（Python 中的文档字符串、Java 中的 javadoc 注释等）提供了类、函数、方法和包的简要摘要。理想情况下，它们应该使读者能够掌握特定代码块的作用。

与代码注释类似，文档字符串有助于保持代码的可读性。但是，尽管前者主要针对将维护和修改程序的开发人员，后者的预期受众则是将使用项目并因此需要了解其不同元素如何工作的工程师。他们最有可能不是与源代码交互，而是通过从文档字符串生成的API或其他文档进行交互。

何时使用以及如何编写文档注释

档注释应伴随每个模块、函数、类和方法，这些是公共API的一部分。这种类型的注释必须

以对象的用途的简要描述开始——它应该是遵循“做这件事”结构的一句话；
提供关于代码部分的详细信息；
提及与片段相关的任何异常和限制。

例如，在定义一个函数时，文档注释应该详细说明它的参数、输入和返回值、何时可以调用等。下图显示了 Python 中 square 函数的文档字符串。

对于类，涵盖其目的、行为、属性和方法至关重要。反过来，每个方法也需要一个关于其用法、参数和副作用的文档注释。添加关于异常的注释通知其他开发人员可能的错误情况以及如何适当处理它们。

文档生成器

每种语言都有其特定的工具，用于从文档注释中自动创建 HTML、PDF 或其他格式的 API 文档：

Python的pydoc、pdoc或Sphinx；
Oracle的Java doc用于Java。像NetBeans、Eclipse和IntelliJ IDEA这样的IDE内置支持javadoc；
DocFX用于C#和其他.NET项目。以及
JavaScript的JSDoc。

虽然主要使用 Python，但 Sphinx 还支持 C++、JavaScript 和其他语言。或者，您也可以使用 Doxygen，这是一个与 C、C#、C++、Java、Python 和 PHP 兼容的开源平台无关文档生成器。请注意，文档生成器仅限于它们在源代码中遇到的注释 — 它们无法添加除注释之外的任何上下文或其他有用信息。

代码文档工具

今天，不同的工具可以帮助开发人员编写代码和文档注释。您可以直接在集成开发环境（IDE）或代码编辑器中访问此类助手，或者轻松地将它们作为扩展添加。虽然数字助理不能为您完成所有代码文档工作，但它们可以节省大量时间。

代码编辑器扩展

许多 IDE 和代码编辑器都附带嵌入式工具、插件和扩展，以改进和简化代码文档。例如，如果您使用 Visual Studio Code （VSCode），这是最流行的代码编辑器之一，则可以利用 Better Comments 或 autoDocstring 等扩展。

Better Comments将注释分类为单行注释、TODOs和其他组，使其更易于使用。该工具支持近 80 种编程语言。

autoDocstring 在 Python 中自动生成文档注释，提供各种文档字符串样式，包括 Google 和 Numpy 的样式，并允许您自定义文档字符串格式。

用生成式AI自动化代码文档

生成式 AI 工具正在成为开发人员日常生活的一部分。由大型语言模型驱动，可以帮助您解释和记录代码。当然，由AI产生的注释和描述应该手动检查以确保准确性和完整性。

GitHub Copilot 主要以其 AI 编码功能而闻名，它还会生成内联注释，解释所选代码片段的行为和用途。它作为 VS Code、Visual Studio、Neovim、JetBrains IDE 套件和 Azure Data Studio 的扩展。

JetBrains AI Assistant是一个内置于IDE的工具，由OpenAI模型驱动)，用于所有JetBrains开发环境，如Java和Kotlin的IntelliJ IDEA、Python和数据科学的PyCharm、.Net的ReSharper等。除了代码补全和重构外，助手还具有“编写文档”功能，以分析选定的类、函数或其他代码段并为其生成注释。

Mintlify Doc Writer 是一款 AI 驱动的文档编写器，支持 10+ 种语言和 9 种格式。要记录一段代码，你所要做的就是突出显示一行或一块代码，然后点击“生成文档”按钮。Mintlify Doc Writer仅作为VSCode或IntelliJ的扩展提供。

ChatGPT 是一种多功能工具，可应用于各种用例，包括记录代码。你可以使用诸如“为以下代码片段生成注释”或更详细的命令，例如“添加注释以解释算法背后的逻辑”或“添加描述函数的输入参数和预期值的注释”。

要使用 ChatGPT 记录代码，您可以将要描述的部分插入 ChatGPT 界面，或者如果有相应的插件，则可以直接从开发环境访问 AI。ChatGPT 扩展的示例包括用于 AssistAI for Eclipse IDE、EasyCode ChatGPT for JetBrains IDEs、适用于VS code的ChatGPT扩展等。

使用 ChatGPT 提示“为以下代码片段生成注释”添加到 JavaScript 代码中的注释

与上面提到的所有工具不同，ChatGPT 有助于生成我们将在下一节讨论的 README 文件。

README 文件

README 文件是向用户介绍您的软件产品的文档。它通常位于项目的根目录中，当人们访问你的仓库时，它是他们看到的第一个软件描述。

每个软件项目，无论其大小或复杂程度如何，都应该有一个 README 文件。

但对于开源项目来说，这一点尤其重要。该文档为潜在贡献者提供有关项目目的的信息以及如何开始使用它的指南和贡献指南。一个精心编写的README文件可以是一个蓬勃发展的社区驱动型项目和一个难以获得采用的项目之间的区别。

README 文件结构

README 文件通常使用 markdown 编写，markdown 是一种轻量级标记语言，用于格式化纯文本的样式和结构。该文件应包含以下部分：

标题 —— 项目的名称和简要说明。
描述 —— 项目的总结、其目的和主要功能。
目录 —— README中的部分列表，链接到各自的标题。
安装说明，包括任何先决条件、依赖项、命令和配置需求。
使用说明，包括代码示例、CLI命令或截图来说明其功能。
功能，帮助读者了解项目的能力。
贡献指南，告知他人如何为项目做出贡献。这包括提交问题、功能请求和拉取请求的指南。
许可证信息，这对开源项目至关重要。
致谢，涵盖对项目中使用的第三方库、工具或资源的致谢。
项目状态 —— 如果相关，提供有关项目当前状态的信息（例如，开发中、稳定、已弃用）。

README 文件的确切结构在很大程度上取决于项目的性质以及它是供内部使用还是开源。例如，内部项目可能不需要贡献和联系信息部分。

如何创建 README

正如我们上面提到的，您可以利用 ChatGPT 来帮助您生成 README 文件。它们的质量将取决于您创建的提示，以使AI理解你想要什么。阅读我们关于提示工程的文章，了解如何有效地与 AI 交流。然而，还有一些其他更简单的工具可以在处理 README 文件时节省你的时间。

Markdown 编辑器对于编写和格式化 README 文件至关重要。它们具有易于使用的界面，并提供实时预览、语法突出显示、目录生成、导出为 HTML、PDF 和其他格式等功能。值得考虑的优秀 Markdown 编辑器包括 Typora、Dillinger 和 Obsidian。

README 生成器可自动创建这些文件，并提供模板和指导步骤。他们确保文档包含所有必要的部分并遵循最佳实践。最广泛使用的 README 生成器之一是 readme.so，这是一种开源工具，提供交互式基于 Web 的编辑器、预构建的部分和模板、实时预览以及拖放部分重新排序。

代码托管平台主要用于协作、版本控制和在存储库中存储代码。但是，它们也支持 Markdown，使其适合直接在存储库中创建和管理 README 文件。例如，GitHub 提供了一个 Web 界面，用于直接在存储库中编辑和预览 README 文件。此外，由于它支持版本控制，因此您可以使用它来跟踪对 README 文件所做的更改以及这些更改的执行者。