程序员:你写文档吗?

上午看了沈剑老师的两篇文章,内容主要关于技术文档。有感而发,下面从个人经历聊聊写文档这件事。

技术人需要写文档吗?

放在 1 年前问我这个问题,我肯定回答不需要。为什么?因为没有体会到写文档带来实质好处。需求代码都写不完,哪有空去写这玩意。

还记得刚参加工作的那两年,那时候不管接到什么需求,都会直接进行撸码,一边思考代码逻辑,一边实现功能。这个过程偶尔会发现一些问题,加班加点也能实现。所以在这一阵时间内,并不知道文档,所以也不会去想着写文档。

后来接到一个需求,需要接入第三方支付,搭建一个基础的支付系统。刚接到这个需求,想想需求实现也很简单吗。无非就是涉及几张表,然后调用第三方支付,完成一次支付。大致参考原有类似系统的实现方案,根据产品给出的需求文稿,没怎么经过仔细思考就开始实现功能,并且还盲目的给出一个工期。

后来实现过程中才发现各种问题,有的是因为项目需求不合理,当前系统根本无法完成这样的设计。所以这个时候需要跟产品讨论协调,如何折衷的改动,最后定下方案,然后删掉写到一半的代码,重新实现逻辑。

其次,原本以为有些功能其他项目组已经实现,直接调用即可。真正对接的时候才发现,他们提供接口根本不能当前需求。没办法只能让其他项目组的同学帮助实现,这就涉及到协调其他组同学开发。

另外这个项目还涉及到与客户端交互,所以需要提前给出交互接口的相关信息。客户端同学按照接口文档,进行接入调试。原以为给出完整的接口信息,可是在客户端同学接入的过程中,才发现有些页面需要新接口,有些接口交互逻辑不合理,这个过程又不得不去重新思考设计。

总之这个项目过程十分艰难,所幸靠着加班加点最终也将其完成。

回顾反思这个过程,我认为最根本的原因在于项目前期没有经过完整的详细系统设计,所有实现功完全按着产品需求流程走动。经历过这个项目之后,慢慢有了一些改变,会提前思考设计,才会去动手写代码。

去年加入现在的公司,公司流程规定,项目需求必须有详细的设计文档。当然,刚开始很反感这种规定,尤其还要将文档写在 word 上。

不过也没办法,慢慢开始接受了这种方式。刚开始以为写技术文档很简单,可是等到真正需要用文字输出的时候,才发现自己竟然写不明白。这个时候就不得不再去思考,去仔细理清逻辑。

今年在几个项目开始体验这种做法,想清楚了系统设计,然后写在文档上。由于前期已经将思路逻辑想明白了,后期代码实现过程照着实现就可以了。

所以现在问我技术人需要写文档吗?

我的回答是需要

引用沈剑老师文档的一段内容:

为什么要写设计文档? 对自己,让自己在动手写代码之前,帮助自己想得更清楚; 对项目,保证信息的一致性,保证项目的可控性,减少项目风险; 对团队,确保知识的沉淀与传承;

文档需要写些什么?

刚开始写技术文档时候,也只是大概写了一些交互流程,表结构设计之类。后面与测试交谈中才发现,他们测试会根据我们技术文档为基础,去设计测试案例。所以文档阅读者不仅仅是开发,还有可能是测试,甚至产品。

所以为了让文档能让大家都看明白,我们需要在文档中体现一下内容。

  1. 需求描述。

阅读一份我们需要文档用途或者目的,所以需要一定需求描述。如果有对应需求文档,可以摘录需求文档描述即可。

  1. 实现逻辑

我觉得最重要是这部分内容,从这部分内容我们可以了解到整个功能逻辑。在这部分功能,最好不要长篇大论,多使用程序图,时序图,ER 图去代替。这些图能很清晰代表逻辑。一些项目需要使用到业务规则,计算规则也可以写在这一部分。

  1. 其他

一些项目难免会存在一些专有名词,可以在文档专门解析这些名词,这样后面描述中使用这些名词也不会让人疑惑。

总之,文档并不一定要按照某个具体格式去写,只要能写清楚,能让其他人理解,我觉得就足够了。

Java Geek Tech wechat
欢迎订阅 Java 极客技术,这里分享关于 Java 的一切。