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

Posted 2020-12-26 kid551

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赞赏专区：