為什麼需要提前撰寫Spec文檔

來自專欄 GeekArtT

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》

如果你喜歡我的文章或分享，請長按下面的二維碼關注我的微信公眾號，謝謝！

更多信息交流和觀點分享，可加入知識星球：

https://t.zsxq.com/FimyJq3 (二維碼自動識別)

推薦閱讀：