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

為什麼需要提前撰寫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》

《不會談》

《編程語言吐槽之Java與C》

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

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

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

推薦閱讀:

(原創文章)如何跳出狐步舞的「輕柔」與「延綿」
代寫原創文章團隊有哪些
「他們都去了大保健,只有我沒去。」
最穩定的婚姻關係,不是靠愛情維繫的

TAG:開發文檔 | 原創文章 |