原文：
www.kdnuggets.com/2022/12/make-documenting-code-easier.html
图片由编辑提供
文档是程序员最讨厌的任务之一。我的意思是，我们是程序员而不是作家。众所周知，程序员在编写代码方面很出色，但在解释他们的思维过程方面可能还需改进。
1. 谷歌网络安全证书 - 快速进入网络安全职业生涯。
2. 谷歌数据分析专业证书 - 提升你的数据分析技能
3. 谷歌 IT 支持专业证书 - 支持你的组织的 IT
这就是为什么我们如此厌恶编写文档的原因。我们需要用文字解释我们的思维过程，以便他人理解。这总是一个具有挑战性的任务。
无论如何，所有程序员都知道良好文档的重要性以及它对任何编码项目成功的重要性，无论是用于开源还是作为团队内部的项目。
记录编写代码的步骤和一些设计决策的理由，对使用代码的人和编写代码的人在添加/删除新功能时都是有益的。
在软件工程中，编写文档通常指的是主要代码开发者编写脚本，详细说明代码的功能、目标以及如何实现这一目标。程序员讨厌编写文档的主要原因是，作为程序员，你更愿意编写代码而不是解释它。
这可能需要读者注意，但在你开始编写代码之前，先起草文档的路线图。这将帮助你两方面，一方面它将让你更容易知道需要在文档中添加什么，另一方面在你开始编写代码时，它将成为你的指南。
我这里所说的“路线图”是你文档的骨架，即你将要解释的不同部分。例如，如果你查看 Matplotlib 的文档，它有四个主要部分：安装、学习材料、第三方包，以及如何贡献源代码。在这些部分中，还有更详细的子部分。
一旦你完成了文档框架并开始编写代码，尝试同时编写代码和文档草稿。我知道我们大多数数据科学家会说，“我会在完成代码后再写完整的文档”，虽然我理解这种想法（即专注于代码编写），但我认为这会使编写文档变得更加麻烦。
在编写代码时起草文档将帮助你理解你在过程中做出的决策，什么有效，什么无效。最后，当你编辑和调整文档时，你可以选择保留那些不起作用的部分，作为展示你如何达到最终产品的方式，或者跳过那些部分，专注于有效的部分。就个人而言，我喜欢保留那些无效的部分，因为它们和有效的部分一样重要。
评论对不同的原因至关重要，但它们不能替代完整的文档。我喜欢将代码中的评论或文档字符串看作是文档中将解释代码不同功能部分的标题。评论将为用户提供他们使用不同函数和/或类所需的最少信息。与此同时，文档将进一步阐述函数的工作原理以及该函数的一些用例。
你是否厌烦编写详细的长文档？我有一个解决方案，如果你的代码组织良好、清晰且编写规范，你不需要详细的文档来解释它是如何工作的；几个示例和教程可能就能达到目的。
在上一篇文章中，我们深入讨论了如何使你的代码更具可读性。幸运的是，编写可读代码是一种可以通过练习直到掌握的技能。
因此，更具可读性的代码会导致更简短的文档。
如果你想学习如何编写清晰、简洁且切中要点的优秀文档，就要多阅读优秀的文档。在这里，我指的是带着学习编写优秀文档的风格和过程的意图去阅读，而不是收集如何使用代码的信息。
我读过的一些最佳文档是 Matplotlib、Pandas 和 Numpy 的文档。这些文档都清晰、简洁且组织良好。作为数据科学家，我们必须使用不同的包来处理不同的算法和应用。我相信你一定觉得某些文档比其他的更好，可能有各种原因。思考一下为什么你认为某些包的文档比其他的更好。这将帮助你了解在编写自己文档时应该避免哪些问题。
产生更好文档的一个好方法是向他人寻求反馈。这可以帮助你了解用户需要/想要更准确的信息、缺少了什么，以及你的文档如何整体改善。
现在，仅仅编写稳健的代码已经不够；为了证明你的能力以及你对项目和领域的熟悉程度，你需要提供撰写良好的文档，并突出显示你的代码如何工作以及如何使用。
不幸的是，我们中的大多数人宁愿花更多的时间编写实际代码，而不是处理文档。在这篇文章中，我们探讨了一些可以使编写代码文档过程更容易的步骤，并帮助你生产出更高质量的文档。
Sara Metwalli 是庆应义塾大学的博士候选人，研究测试和调试量子电路的方法。我是 IBM 的研究实习生和 Qiskit 倡导者，致力于建设一个更加量子化的未来。我还是 Medium、Built-in、She Can Code 和 KDN 的作者，撰写关于编程、数据科学和技术主题的文章。我还是“Woman Who Code Python”国际章节的负责人，火车爱好者，旅行者和摄影爱好者。