为什么需要提前撰写Spec文档

发布日期:2019-02-03

Joel on Software(中文名叫《Joel软件随想录》)算得上是一本旧书了,但里面的建议和讨论,真的是历久弥新。特别是,Joel是个有趣、牛逼的家伙:前微软Excel的职员、Stack Overflow的创始人、Trello的创始人,以及他和他的boyfriend走入了婚姻殿堂。这本书,是Joel自己blog文章的一个精选集。

Joel在这本书里谈到了很多技术性的观点,高屋建瓴地从思想方法上去讨论如何看待程序、看待公司、看待构建过程。著名的The Joel Test也出自于此。

这本书我很早就知道,但一直没有机会亲自阅读。最近读了几章,便爱不释手。按理说,我应该将这本书读完后再写点评论。可是,它已经如此优秀,让我在这个阶段就想要开始对它做一些介绍和吹捧。

很遗憾,自己读这本书还是晚了些。要是能够在最开始学习技术的时候就读到,想必能少走不少弯路。以我自己的观点来看,要掌握任何一个领域的技术,一个很重要的点就是一定要聆听大师的指导。如果你运气够好在自己身边遇到了一位大神,你可以直接向他请教。而如果没有这样的运气,那自己便需要多花费点功夫,去找大师写的文章和著作阅读,特别是那些关于review和观点的著作。因为,对于一个初学者来讲,刚进入一个领域,他有且只能看到繁复的细节,并不知道该以何种方式在脑海中把这些凌乱的碎片,系统、有条理地在脑海中组织起来。所以,阅读大师的这些综述性的著作,其目的,就是要在脑海中建立正确的看待这个领域的思维框架。

Joel关于Specification文档撰写的讨论,就是一个很好的例子。对大部分不合格的programmer来讲,写文档、写注释是一件无足轻重、讨厌至极的事情。在他们眼中,唯有代码是真正值得关心的东西,因为只有代码才可以让计算机工作啊,而一堆论述性的文档,写出来也无法被运行,那不就是浪费时间吗?!

而对另一群程序员来讲,代码恰恰是最后的、水到渠成的结果性的东西,不是你应该花费大量时间耕作的东西。对他们来讲,如果你能够写出清晰、细致的文档,代码自然就会优质卓越。如同揠苗助长这个故事的寓意,你无法通过把秧苗拔高,来加速秧苗的成长,你能做的,是更好地耕耘、施肥,尽力提供促进植物生长的环境。单纯地把精力花费在代码的细节上,就是在强制性地拔高秧苗,希望通过最直接的方式,来加速你项目的完成。而写文档,则是提前为后面复杂的代码提供良好的生长环境——清晰准确的逻辑。在这样的牢实的基础上,你的项目自然可以快速成长。

大部分做技术的人,会过分地注重勤于动手,而忘记了更重要的一步——先动脑。在他们看来,“开大会、打嘴炮、写文档”,都是一些business上的该死的流程,都是在务虚,不务实。由于已经在脑海中定下“无用”的论调,自然更是没有机会去理解其中的精髓。

“开大会、打嘴炮、写文档”,如果用讽刺的话来讲,就是“纸上谈兵”。可是,还有另一个褒义的描述——沙盘演练。对于任何一个项目来讲,前期的需求确认,是极其重要的。因为它是后续所有流程的根基。流程的更改、方向的变更,如果发生在技术开发的过程中,其损害的成本非常巨大,你不得不调整构架、重新组织甚至删除你已投入大量精力的工作。而如果这个事情发生在似乎不怎么有用的“开大会、打嘴炮、写文档”呢?那无非就是多耗费一点口水,重新写一行文字罢了。

撰写spec文档,就好比是画家最开始在画板上勾勒的辅助线。粗糙的一横、一竖,潦草的正方形框、椭圆形脑袋,不一而足。而如果你去观察刚学画的小朋友,大多有一个共同特征:几乎无法经受住描绘细节的诱惑,一开始就精细地刻画眼睛、嘴巴、肌肉的纹路。而最后的结果也是理所当然的四不像,错位、扭曲、畸形的五官与大小各异的四肢组合。通常,老师会花费大量的时间去纠正初学者这种从局部出发的坏习惯,让他们逐渐适应、掌握从整体的框架出发,再逐步深入细节的技巧。

写代码和写文档的关系,就是这样精致描绘细节和简单勾勒草图的关系。

当你所写的项目稍微多涉及几个现实的事务,其业务逻辑就不会如你现象中的那样简单。例如写一个用户登录的输入框,乍一看,似乎没什么精细复杂的地方,于是大摇大摆地动手写起代码来。行至途中,通常会发现各种小问题,前面忘记一个验证数据,后面忘记一个记录cookie,搞得自己狼狈不堪。可如果你肯多花费一点时间,将spec文档写好,把每一个流程图、状态图庙会清楚,就等于是为后面的代码撰写提前做了一次沙盘演练,能让你成竹在胸。

而另一方面,软件开发是协作性的事物,仅仅是团队工作中的一个环节。你对代码的理解,往往只是代表你自己的个人意见,难保与你合作的产品经理、老板、其他部门会有不同看法。难道要把整个项目都写完,才去征求他们的意见吗?!

这就是提前撰写spec文档的另一个好处:你可以在写代码之前,就把流程理解记录下来,让项目相关人士提前审阅,从而以最小的成本,提前修正方向性的争论和问题。

 

 

 

近期回顾

《叫兽的逻辑 | #Metoo》《不会谈》《编程语言吐槽之Java与C》

 

 

如果你喜欢我的文章或分享,请长按下面的二维码关注我的微信公众号,谢谢!

 

 

更多信息交流和观点分享,可加入知识星球:

 

 

VIP赞赏专区: