聊聊 API 文档

javascript/jquery

浏览数:129

2019-3-6

1. 为什么大家不想写文档?

绝大部分开发人员对于写文档这件事的态度都是排斥的。

为什么大家不想写文档呢?这不是没有原因的。大家心中都有自己衡量每件事价值的标准。代码是必须的,不得不写,这逃不掉。但是文档并不是必须的,即便没有文档,口口相传也可以解决问题。所以这件事的价值取决于这份文档到底会被用到多少次,而大部分时候这是无法预测的。

如果可以预先知道文档最终会被大量阅读,开发人员就不会排斥写文档。一个典型的例子就是 Open API。如果一套 API 的消费方是个已知的庞大群体,作为 API 的开发人员,口口相传就不能解决问题了,这种情况下写文档就会变得像写代码一样自然。

所以大家不想写文档的根本原因是不想对回报率未知的事情做投入。

2. 回报率就是低

既然我们知道了问题的根源,要解决当然就是想办法让写文档变成一件回报率明确的事情。这说起来简单,实际操作起来往往会出现明确回报率后发现回报率确实低的情况。比如某项目参与的前后端人员各一个,对于后端人员而言,写文档的目的是明确的,就是给前端一个人看。

我个人认为,如果文档只写给一个人看,那还真没有写的必要,直接沟通效率明显更高。然而这种「文档只写给一个人看」的场景在日常工作中却是常态。除非是开发 Open API 这类东西,一般的业务对接都是针对性很强的。

有些团队对于 API 文档的要求就是简单的一条规定「必须写」。这种强推导致的结果是最终产出的文档会非常敷衍的,比如偷懒直接把 API 定义抄一遍作为文档。于是名义上有了个叫做文档的东西,实际开发人员对接过程中对于细节依然是口口相传的。因为个体都是逐利的,回报率确实低的事情是无法强行推成功的。

3. 文档的本质

我们先暂时抛开前面那些不愉快的问题,冷静下来思考一下文档的本质到底是什么?

  1. 文档写出来真的只是给某个人看的吗?
  2. 文档真的必须由 API 提供方来写吗?

如果只是给某人看的,文档和邮件有什么区别?如果前后端开发人员对接的时候直接在邮件里把 API 相关的详细介绍和用法发给对方,这可能比找一个地方存放文档,然后发一个链接给对方让别人自己去看更好。所以文档可能不仅仅是为了给某人看这么简单。那么文档是不是可以是一种落地的契约呢?

既然是契约,那就肯定不是单方面制定的。所以是不是前端开发人员也应该参与这个契约的制定呢?

编写契约的回报率肯定比「只写给一个人看」要高得多,至少这是两个系统之间的契约,是可以解决问题的。而且两端的开发人员共同制定这个契约就分摊了原来的投入。投入降低、回报增加,自然就解决了前面的问题。

只要把对文档的认知提升到契约的程度就不会再排斥写文档了,因为契约比代码更重要。

4. 契约精神

在互联网高速发展的过程中出现过一批自我认知良好的「极客」,为了解决写文档的问题,使用一种「代码即文档」的方案来避免额外的文档编写成本。具体做法是在代码中通过注解或注释等手段来直接编写文档,最后通过工具生成出来。

我认为这种操作是对「自动化」的过度崇拜。没有从根本上挖掘文档的价值,只是通过技术手段来降低文档的编写成本,结果和强制要求写文档一样,最终产出的文档会非常敷衍。

契约精神就是契约先行,代码实现反而应该遵循契约。在文档的概念停留在「只写给某些人看」的时候,会遇到 API 版本更新,但是文档没有跟进的情况。一旦文档被视为契约,那么所有 API 实现与文档的差异都不是「文档没有跟进」而是 API 实现不符合契约,是 API 实现有问题。

缺乏契约精神的前后端对接是很空洞的。假设有一组前后端开发人员,后端使用「代码即文档」的方式来提供文档。早上前后端联调完毕,到了下午后端认为自己的代码可以进一步优化,修改了代码重新生成了文档。这时候测试发现跑不通,那么是谁的问题?

没有契约就不能确定一个东西它应该是什么样的。如果 API 永远以提供方为标准,那谁还愿意作为消费方?

5. 最后

解决问题不能光想着怎么从技术层面做好,还应该思考事物的本质。把一件事抽象到一定程度就可以和其它领域的另一件事拟合。

有没有发现「写文档」这件事和「生态文明体制改革」一样,对于执行者自身而言是一件回报率未知的事情,是一种类似于「功在当代、利在千秋」的事。

这类问题的解决方案可以借鉴习主席在十九大报告上对「加快生态文明体制改革」的具体举措。其中首要就是「加快建立绿色生产和消费的法律制度和政策导向,建立健全绿色低碳循环发展的经济体系」。这里的「法律制度和政策导向」就是「看得见的手」,最后的「经济体系」就是「看不见的手」。整体是经济导向,明确了人们心中对这件事的回报率认知。举个例子,如果只是让大家高喊「生态文明建设」这个口号,那估计没有谁会买账,但如果是做类似扶持新能源汽车这样的实事,那就可以让人们看到明确的回报,让「生态文明建设」变得更加具体起来。