💻 文档即代码

程序员讨厌写文档。至少大多数程序员都讨厌。文档只会妨碍他们真正地工作™，不是吗？

事实上，编程的“真正工作”（Real Work™）主要由一些不直接编写代码的事情组成。例如确定规范、设计 API、探索技术限制、学习最佳实践、培训他人等等。

即使程序员直接编写代码，代码本身也必须在有时相互排斥的目标之间找到某种中间立场：

• 代码必须解决当前的问题。
• 代码必须易于维护。
• 代码必须足够高效。

为了便于维护，好的代码必须为人而写。具体来说，是为其他人而写。即使你是一个独立开发者，未来的你也会是一个不同的人，至少就你现在编写的代码而言是这样。

解决这个问题的一种方法就是所谓的“自文档代码”。这种方法的核心在于将精心设计的变量和函数名称与简洁的代码实践和行业标准相结合。

自文档化代码也是一个很好的做法，因为它可以减少代码之外所需的文档量（例如注释）。除了描述代码的注释之外，还包含其他代码会违反“不要重复自己”（DRY）原则。DRY 的目的是防止因在一个地方修改了某些内容而在另一个地方没有修改相同内容而导致的错误。如果只有一个地方，这种错误就不可能发生。

但是，如何记录更宏观的内容呢？一个项目的总体目标是什么？它的切入点是什么？谁应该使用它？它的依赖关系是什么？它上次更新是什么时候？它使用的是什么编码标准？

保持项目文档的 DRY 原则比代码的 DRY 原则难得多。这就是我们引入“文档即代码”（借用“基础设施即代码”的概念）的原因。其目标是让每一份文档都以某种方式与项目本身的功能耦合，这样，如果其中一份文档发生变更，两份文档都必须随之变更。

无论如何，只要有可能。

我承认，我在这方面一直做得很糟糕，并且正在努力寻找方法，在我的项目中显著改进。我没有一个完美的解决方案，但以下是我一直在思考的一些有用的概念和工具：

• 全局约定。我所说的“全局”是指跨项目和团队。遵守约定也是一种文档。例如，如果每个人都知道事件触发函数总是以on（例如onDownload()）作为前缀，那么就可以使用更简单的函数名，而无需添加注释。或者，如果每个人都同意回调函数总是以error参数开头，那么每个人的代码都可以利用这一点，而无需额外的文档。
• 配置无处不在。像“Cosmic Config”这样的工具，让您可以轻松地同时遵循行业通用惯例，同时按照自己喜欢的方式进行操作。通过将信息放入可解析、可测试的配置文件中，这将带您进入“基础设施即代码”和“环境即代码”的领域，进一步减少文档需求。
• 让一切自动化。如果机器人能做某事，人类就不需要了解它的具体运作方式。如果你需要在项目中定期做某事，那就把它变成代码吧。
• 避免设置错误。所有优秀的工具都包含一个init命令（或类似命令），以便用户轻松上手，并最大程度地减少错误。最好的工具会通过人性化的问题，以交互方式引导用户做出必要的决策。理想情况下，用户甚至无需查看生成的配置文件。
• 文档和代码应该具有相同的依赖关系。这是一个棘手的问题，但也是我最感兴趣的。它让人想起依赖倒置原则。其理念是：我们通常将文档视为依赖于代码，但如果两者都依赖于其他内容呢？这样，我们就可以对其他内容进行更改，从而使代码和文档保持一致。

对于最后一项，您肯定需要用代码构建文档才能使其正常工作。一个简单的例子是使用配置文件——构建文档的代码可以从与您的代码相同的配置文件中读取值。实际上，您越能将概念抽象为模块化代码或数据，就越能在自动化文档和代码中使用。

API 文档可能是最好的例子，特别是对于像 JavaScript 这样灵活的语言：您可以使用集中式 API 文档来规定代码的功能和描述它的文档！

为了实现这一点，您可以使用Swagger/OpenAPI、joi、Express Validator等工具。

我才刚刚开始尝试做这件事。你用了什么技巧和工具？

本文最初发表于DevChat 新闻通讯中。