良好文档的4条原则(翻译)

原文地址: The 4 Tenets of Good Documentation

我最近和一个我带的初级开发人员讨论代码文档，并提出了良好文档应该包括的四件事。在向我的学员讲过这一点之后，他们惊讶于为什么以前没有人如此简洁地说过。所以我决定写下这些原则，以防读者也看不到它们。

好的代码文档必须告诉下一个开发人员（即使是同一个人）以下四点信息：

• 目的：为什么编写代码（是库，代码段，方法或类）
• 功能：代码在做什么，
• 形式：代码如何实现其功能，以及
• 用法：如何使用代码。

在本文的其余部分中，我将使用 PieChart 类作为示例，该类的编写目的是在屏幕上显示饼图。这是一个非常简单的概念，它完全封装了可能会被重用的单个功能。

目的：为什么要编写代码

为什么创建这个 PieChart 类？在我们的示例中，它封装了向用户显示饼图所需的所有代码。在我们的应用程序中，我们将显示很多饼图，因此，最好有一个编写良好的类来处理它们。因此，此类的简单目的是使显示饼图更易于编码。

一般来说，这是最容易编写的文档。一方面，这纯粹是观点。编写该类的原因是你想要或需要编写它。你只需要将其目的传达给下一个开发人员。这样，你可以让下一个人看到它，以了解它为什么对你创建的整个项目或库很重要，他们将更好地掌握如何在代码中使用它。此外，文档的这一部分不必冗长。它只需要足够的信息告诉开发人员到底是什么。

在文档的这一部分中，你还应该列出编写此代码的所有假设。在这里，你可能要列出此代码的替代方案，这些替代方案可能无法满足你的特定要求。

目的：

PieChart 封装了显示饼图的功能，给用户一个可重用的类。

功能：这段代码在做什么

这是你编写的代码的高级描述。在我们的 PieChart 类示例中，代码将获取用户数据并将其显示为饼图。但是，该描述过于简洁，实际上只是”目的”部分的重复。

我们需要做的是解释 PieChart 的所有部分都在做什么。在提供表格文档时，可以将其分解为多个部分并进行解释。不过，对于复杂的代码，最好对功能进行汇总，并与代码原理的解释分开。

功能：

PieChart 接收用户数据并将其转换为可显示的格式，然后呈现给用户。饼图使用本地图形库创建，并使用提供的字符串进行描述。饼图可以在屏幕范围内创建为任意大小，并且可以放置在屏幕上的任何位置，只要它们完全在屏幕范围内即可。饼图将使用一组计算出的颜色创建，以提供各部分之间的对比。如果需要，也可以设置颜色。

形式：此代码的工作方式

现在我们需要深入研究代码。这是我们在这里解释所使用的所有微妙技巧，所使用的所有复杂算法以及代码进行的所有假设的地方。并不是每个方法或属性都需要单独文档化，特别是如果它们的名称是见名知意的。但是，复杂的方法和方法参数绝对应该如此，特别是当可以使用编辑器自动完成查看注释时。

这里的文档应该是这样的水平：如果要让其他人去看（或者如果你要在6个月后再回来查看它），不会有关于它如何工作的问题。这可以说是最华丽的赞美了。

在这里，你还需要解释为什么选择一种算法而不是另一种算法，尤其是当你使用的算法是非标准算法时。对于大多数类型的软件，有许多标准实践，如果你的代码将要偏离这些标准，请提供充分的文档说明其原因和方式。我知道作为开发人员，我们有多喜欢在我们的代码中利用巧妙的技巧。但是，如果你没有足够地证明这种聪明才智，那么没人会理解或信任你的所作所为。

以下是 PieChart 的一种方法 DrawChart() 的一个很好注释的示例（在此缩写为空格）。

格式：

/ * 
此方法DrawChart（）包含用于
在屏幕上绘制图表的所有图形代码。它希望从类属性中知道大小
（半径），中心位置，数据数组，颜色数组和
描述数组。没有这些，该
方法将失败。绘制循环：根据数据计算圆弧，从中心到圆弧
起点绘制线，绘制圆弧，从圆弧末端到中心绘制线，填充
颜色，创建描述字符串视图，基于
圆弧旋转视图，绘制字符串视图。该方法将在失败时引发错误。
* / 
func DrawChart（）

用法：如何使用此代码

最后，我们需要描述如何使用代码。对于某些代码，这是可选的，但前提是用法简单，明显且易于从代码中推断出来。通常只有使用简单方法或高度描述枚举之类的代码时才如此。其他所有内容均应使用，并在可能的情况下以自动完成编辑器可以理解注释以及自文档库可以读取它的方式添加注释。

用法：

PieChart.init（Array userData []，Array userColors []，Array 
description []，double radius，point centerPoint）userData是一个值数组（双精度），将用于
计算饼图的百分比部分。userColors是一个可选的颜色数组，
每个值与一个颜色匹配。descriptions是一个可选的字符串数组，显示在
每个楔形中，每个值与一个匹配。radius是饼图的半径。centerPoint是饼图的中心，是一个点结构
（双x，双y）。

第五条宗旨：乐趣

编写或阅读文档通常都不是很有趣。如果做得正确，文档能提供很多信息，但文档通常很枯燥，有时很难理解。我喜欢在我的注释中搞些幽默，我鼓励你也这样做。一个无伤大雅的，有目的的双关语或基于上下文的笑话常常受到读者的赞赏。不过要注意政策。一些老板对此不满意。

结论

好的文档是成为优秀开发人员的一部分。如果没有其他原因，我鼓励每个开发人员养成为代码写文档的习惯，他们将能够理解自己所写的内容。而且，我向你保证，如果你勤奋地编写良好的文档，你的同事和合作者将为此而喜欢你。

打赏