为什么要写文档?

有必要吗?

万事万物我们都需要一个场景

在不一样的场景下会有不一样的答案和选择

我们作为一个程序员,有必要写文档吗?

我本人非常喜欢刷题,还有捣腾一些好玩的小东西

当我刷题时,或者说做某种单一功能时,目标非常明确时,我们的确不需要文档.

因为有写文档的时间,我们这个功能都搞完了.

但是,换一种场景,在我们的工作中,我们需要吗?有必要吗?

有些人是比较懒,有些人是感觉不到这么做会带来什么好处.

对于这种问题,我也只能从自身出发谈这个问题

一般情况下,我们接到任务后,在脑海中简单过一下,问一下分派人要查哪些表,哪些字段,显示什么等等,基本流程也就结束了,最多就是做着做着发现做不下去,再去问一下,哪里哪里是不是这样的,以排除问题,推进任务的前进.

这样做有问题吗?

我觉得这没有问题,而且也是很普遍的现象.

但是,这个时候,或者过了几天,出现了Bug或者业务方有新的需求或改动

我们怎么办?

找到原来的代码,思考一下加在哪?哪些会变?或者哪个部分会出现问题.基本靠阅读代码是无法排除问题的,一般都会在入口处加上一个或多个断点然后开始一步步调试.

好了,上面就是我面临的问题与困惑.

而且这个困惑会随着任务目标的复杂度而呈几何性增长,并且每一个问题的出现及变动都是非常恐怖的事情.

这样也往往导致了,我在完成某一任务后感觉如释重负,一点都没有成就感,并且随着不断维护会加剧对抗抵触心理.

我可不是危言耸听,这是我真真切切的感受,这实在是太难受了,你在工作时的心思需要记住你这个功能点所有涉及到的方方面面.试想,记住每一个细节,每一个为了实现这个功能而对应的程序的动作.如果你同时负责多个模块....

这是站在个人的角度在思考这个问题,可以看到,每个人和自己负责的部分高度绑定.

这种重要性真的好吗?

我们来看看站在团队的角度会发生什么?

在初期,平安无事,中期会出现一些互通链条的部分,动作不顺畅,后期会出现大范围的测试,然后导致问题接连暴露,之后是可想而知的赶紧搞完.

当然避免此类情况的方式也是多种多样的,取舍点在于成本.

整个团队会出现疲态,日积月累下导致的重复积累,也不会结出有助于下一个,再下一个项目的关键性的帮助.

可想而知,在未来的某一个项目,有某个类似动作时,会忽的想起自己或者团队曾做过类似的事情而去翻找以前的代码.

在我看来,是非常恶性循环的部分.

现在,我们来看看另一种可能的假设

在接到一个模糊任务时,先将动作分割,先做A动作,然后B动作,这两个动作之间有没有关联性,我做A动作需要什么帮助?我的B动作需要返回一些什么?

我在实现这个功能时,需要哪些表,表与表之间的关系是什么,能不能列一个sql语句脚本,用来自我验证?

哪些地方可能会有隐患,我不能十分确定?

如果这样做了之后会有什么改变?

这也是对于不同任务指数有不同的反馈效果,对于非常简单,一目明了也就是说通过代码就能明白要干什么的任务时,完全不需要文档,即使后期更改出现问题,定位起来也非常容易.

但是对于有动作关联嵌套的,也就是直接阅读代码会带来结果猜测的,在后期变动和问题定位时,将非常快的找出对应的动作部分,和想要的sql,以更好的帮助自己,团队做出响应.

再从长期来看,对于个人而言,快速定位问题,对业务变更,可以根据变更点,较快发现对应代价,是做不了让业务方更改需求等级还是重写代码.对于自身问题分析能力的提升也是显著的.并且在代码层面,更好的理解各个动作之间的关联性,各个动作之间是否可以有个公共类或者公共接口,与别人一起合作时,也能让人更好的理解你为什么要这么做,而不是告诉别人你是怎么做的.怎么做,做了什么,这个部分应该让代码本身来解释.

对于团队而言,更好的把控周期,控制节点,对未来的扩展性也提供了可能,对于任务的分派,其中关联性的占比,做出先后和不仅仅是模块间的关联.并且在进展后期,也可以对这个业务产生更好的理解和总结更多的有助于以后的经验和帮助.在未来团队成员更替后,对于项目本身的不稳定性也大大提升.并且对于业务方更提升了团队专业化的认可,也对既有问题有深刻的认识.

这种文档不是一开始定型之后就不做改变的,而是随着项目的进度进行着迭代.

文档的建设因功能和作用大致分为:

开方文档(我要干什么,打算怎么干,为什么这么干)

数据库文档(哪些SQL重复,哪些表重用度高,SQL应该带来怎么样的预期表现)

对外接口文档(比如给微信小程序的接口)

对内接口文档(程序内部调用的接口)

测试文档(列出各种动作的可能,配合数据库语句)