zs

好的协作从注释开始

不健全的文档成为API测试的拦路虎

如果问一位研发人员:编码过程中最痛苦的事是什么?修改他人的代码肯定在列,面对不完善的注释,难懂的逻辑往往让他们束手无策。江边望海作为一个曾做过开发的测试人员,一直都有着双重人格——从研发的角度去思考测试,从测试的角度去观察研发。

分层测试模型

图一:经典的金字塔式的分层测试模型

如图一,UI层的测试投入小,见效也小,往往测试团队就可以独立完成;Service层即API层,投入适中,收效也可观,但需要测试和开发一起配合完成。越往低层走越需要研发的支持,越往低层走对产品质量的提升越大。那么中间层的API测试如何进行呢?

摆在API测试面前最大的问题就是没有健全、稳定的接口文档。如果让开发人员写完代码再去整理接口文档,积极性一般不会很高。

一次偶遇终身难忘

2年前,当我第一次接触yii的时候(那个时候yii还是1.x版本)就被它漂亮的手册所折服。不禁感叹:怎么可以有这么漂亮的接口文档。

yii文档截图

图二:yii的文档(文件关系,详细的使用方法让使用者一目了然)

其实,当时做开发的时候也做过尝试将注释生成文档的做法。当时用的是phpdoc,由于生成的文档太过于简陋,不仅一般人没法看,甚至是开发人员也不愿意面对,所以就不了了之了。

我们都知道,企业最大的成本之一是沟通成本。工作交接的时候,你写的代码我看不懂,我写的代码你看不懂。我需要反复的解释我写的代码的用法。如果让其他人来整理我的文档,又会曲解我的本意,质量肯定也好不了哪去。新人入职后面对不规范的文档还需要反复的问,即挫败了他的情绪,有降低了核心成员平时的工作效率。

更关键的是,由于文档不全,测试很难介入到API的测试当中。

念念不忘,必有回响

那么,问题来了。如何才能编写一份儿健全的文档呢?大概有以下几点

1.谁开发谁编写;
2.API接口文档应该不需要另外在投入精力编写;
3.根据注释自动生成;
4.让文档成为团队协作中来,提升它的价值;

代码

图三:直接在代码中注释

生成的文档

图四:根据代码中的注释,自动化的生成的文档

工具善其事,必先利其器

图四的文档正是我使用yii apidoc自动生成的。yii api-doc也是我迄今为止看到过的最好的文档生成工具。

安装起来非常简单。在Centos服务器上安装Composer,然后使用Composer执行以下命令进行安装

php composer.phar require --prefer-dist yiisoft/yii2-apidoc

分析源码

vendor/bin/apidoc api source/directory ./output

代码注释风格的撰写以DocBlocks为标准撰写即可,网上有专门的文档介绍如何编写。

关于apidoc的更多使用技巧,请访问:https://github.com/yiisoft/yii2-apidoc

《好的协作从注释开始》有2个想法

发表评论

电子邮件地址不会被公开。 必填项已用*标注