原文标题 ：How to Write Good Code Documentation for Data Scientists

如何为数据科学家编写好的代码文档

有关确保每个人都理解您编写的代码所需的最佳实践的速成课程。

编写好的代码文档的数据科学家很像工程师，确保支撑桥梁的支柱能够承受桥梁本身和使用它的乘客的重量。

代码文档不仅提供了代码功能的概念，而且还让其他人了解编码器的思维过程以及为什么必须以某种方式编写代码。

每个人都有过这样的经历，他们被扔掉了一段旧代码并被告知要重新编写它，或者更糟糕的是，一段代码需要与现有流程集成。在这些情况下，如果有良好的代码文档可用，这是一项容易完成的任务。但是，如果不存在代码文档，这可能成为一项不可能完成的任务，从而导致时间、金钱的损失，并可能破坏系统。因此，代码文档与支撑承重桥的支柱一样重要。

鉴于许多数据科学家并非来自基于编程的领域，或者不相信代码文档是必不可少的实践，因为数据科学家通常与组织的其他成员隔离开来，数据科学家甚至可能不会编写任何代码是完全正常的代码文档。

因此，如果需要代码集成，为了在未来从事代码工作的数据科学家和工程部门之间保持和平，请查看以下可用于编写良好代码文档的最佳实践。

编写分步说明，描述您的代码如何工作以及使代码工作所需的步骤。

您在编码过程中编写的注释将是您开发代码文档的基础。

最初处理代码时，您希望首先编写详细的注释来描述过程的每个步骤。

然后，这些笔记将用于编写您的文档，并将为您的思维过程提供最准确的一瞥。这对于避免历史上每个程序员都遇到过的问题也很重要：从一个周末离开你的代码回来，不记得你从周五开始的原始思维过程，这在当时是完全有意义的，但现在对你毫无意义。

这些注释可以写在您的代码中（最有帮助，但请记住在生产时间临近时清理它们）或单独的文档文件。

这里的关键是写下编写代码时想到的所有内容，尤其是那些你可能认为无关紧要的事情，尽管最终可能会在以后的使用中改变游戏规则。这包括诸如描述每个变量代表什么、每个函数做什么以及代码应该产生的结果等项目。您还需要说明为什么必须以某种方式编写代码以及函数的使用和调用顺序。

假设阅读您的代码的人一无所知。

假设阅读您的代码的人对代码的作用、工作原理以及工作原理一无所知。

太多次我遇到过一段几乎没有文档的代码，编写它的人很明显地认为下一个人会知道它的一切，从它是如何工作的，到为什么它必须被写成特定的防止破裂的方法，甚至做到了。

因此，在编写代码文档时，您可以做的最好的事情之一就是编写它，就好像下一个人不知道与您的代码有任何关系一样。

这涉及将您在开发代码时编写的注释拼凑成对该人将要查看的代码的完整解释。如前所述，此信息可以驻留在代码中（同样，如果连贯，最有帮助），也可以驻留在外部文档中。

简短的注释应该包含在代码中，而长篇的解释或描述最好留在外部文档中，尽管个人偏好或公司政策应该是决定因素。

使用编码约定和最佳实践。

当您编写的代码甚至没有遵循正确的编码约定和最佳实践时，要帮助人们理解您编写的代码是很棘手的。

尽管此讨论超出了本文的范围（您可以在此处查看我关于数据科学家软件工程实践的完整文章），但主要思想是确保您编写的代码干净、易读，并且遵循适当的软件工程标准。这不仅可以帮助您之后的人理解代码，而且还可以使代码尽可能地为生产做好准备，如果时间到了。[0]

在编码约定和最佳实践方面要关注的关键思想是：[0]

• 使用描述性变量名称。
• Use functions.
• 使用注释（如上所述）。
• 使用一致的编码风格。
• 使用您使用的语言的语法约定。
• Use libraries.
• 保持代码干燥。

你明白了。

使用编码约定和最佳实践可确保，如果您的代码文档低于标准，那么熟悉代码的人可能能够理解您编写的内容以及它应该如何工作。

此外，这可确保您的代码文档有意义，因为它将遵循您正确编写的代码的形式。

提供您的联系信息。

你会惊讶于能够打电话给你正在使用的代码的作者并要求他们用小词解释它是如何工作的是多么有用。

有时，文档还不够。或者，文档在特定领域可能不是特别清楚。或者您需要与作者确认他们所制作的作品应该如何工作。

在代码或文档末尾提供您的联系信息是一种简单而有效的方法，可确保将任何问题或问题直接发送给您，这有助于节省时间、金钱和挫败感。

Use flow-charts.

以图形方式查看流程可能是了解其工作原理的一种极为有效的方式。

流程图是我在大学时学到的东西，至今仍在使用，以确保我了解我的代码应该如何工作。虽然有些人可以通过阅读来理解，但我通过查看插图或图形来理解。

这些流程图可以包含在您的代码的外部文档中，并且应该提供关于函数如何工作、它应该返回什么以及如果出现问题或条件不满足应该发生什么的分步说明。

这些图形不仅可以帮助下一个使用您的代码的人，而且还可以帮助您生成更清洁、更有效的代码。

练习描述你的代码是如何工作的，这样一个 5 岁的孩子就能理解它。

在完成你的代码文档时，你要确保你可以向一个 5 岁的孩子解释你的代码是如何工作的。如果你没有一个 5 岁的孩子来解释你的代码，那么仙人掌或橡皮鸭也同样有效。

这种做法背后的想法是确保当某人不可避免地遇到您的文档无法回答的问题时，您可以完整而简洁地回答他们的问题。此外，这可以帮助您检查是否遗漏了文档中的任何关键点，或者您是否需要修改对特定场景、功能或结果的描述。

通过在提供代码文档之前对其进行几次审查，您可以确保您可以通过文献尽可能简单地解释您的代码，并且如果出现问题，您可以更详细地解释它。

Key Takeaways

• 在整个编码过程中，写下可用作文档基础的详细注释。
• 在编写文档时，假设读者对您的代码、代码如何工作以及为什么工作一无所知。这将为您提供编写任何人都可以理解的全面文档的最佳机会。
• 使用语法约定和最佳实践编写代码，以便在您的文档没有提供所有答案的情况下，下一个用户通常能够理解您的代码。
• 提供您的联系信息，以便下一个用户可以直接向您提问。这为每个人节省了时间、金钱和挫败感。
• 使用流程图提供代码如何工作的图形描述。
• 练习向 5 岁/仙人掌/橡皮鸭解释你的代码是如何工作的，以确保你在文档中包含了所有关键点，这样如果有人提出问题，你可以提供进一步的解释。