< 返回

维护项目文档的重要性

2022年1月1日

2021.11.29 我开始在杭州哈啰出行实习,我所在的小组负责的是供应链 APP 的开发,采用 Flutter 模块化开发。

# 对于模块文档缺失

模块化开发的页面非常多,拿我部门的项目来说,我实习刚入职那会,就有十几二十个页面了,并且这只是一个项目,部门负责的不只有一个项目。

在我接到前两个需求的时候,我就发现了一个问题,我们部门很少维护项目相关的文档。

这导致了对应模块的相关资源文档缺少整合,造成了新成员对需求理解度的降低,寻找项目原有的一些资源也很不方便。我还记得当时要一个页面的相关接口,得靠另一个同事在他的聊天记录中到处收集后整合给我。

这其实不止对新人接手项目不友好,对于后期维护也比较麻烦。

# 渐进的解决方案

如果没有制定特定的规范让大家形成对需求资源整理的习惯,维护一份文档其实也不容易,因为在新需求开发过程也可能发生文档更改。

因此在部门的一次 Code Review 中我提出了使用 dartdoc (opens new window) 注释来做相关链接。

  • 在对应页面代码的 Widget 类上写上对应的 PRD 链接
  • 在对应后端接口的 URL 上写上对应的 YAPI 链接
  • 对于有页面参数传递的情况,写上链接至数据来源的页面

dartdoc 支持 markdown,因此跳转到代码外部链接也很方便,对于新人看到这段代码可以通过该提供的 PRD 链接来了解原本的需求,对于接口调用的后端接口,也可以马上找到对应的接口文档来查看接口参数和响应数据格式。

对于后期维护和其他人接盘也会方便很多。