大多數(shù)程序員，都極度痛恨寫文檔。Coding是愉快的，而Write是痛苦的。有一部分原因，其實是要歸咎于程序員自身，以我的經(jīng)驗，很多程序員往往會“艱于表達”，尤其是用“文字、圖表、PPT、Word”之類的Office Document來表達。當(dāng)然，還有一部分原因，是由于很多項目開發(fā)實踐中，文檔的前后矛盾、形式主義、反復(fù)修改、歧義重重，常常讓程序員們抓狂。
?
UML是一個比較好的工具，但是，僅僅靠UML，是無法將項目的知識描述清楚的。也有不少項目組在引入了UML之后發(fā)現(xiàn)，文檔的工作量不但沒有減少，而是更多了。隨著項目的進展，需要維護的設(shè)計文檔數(shù)量，也更多了。也因此造成了更多的前后矛盾，形式主義，反復(fù)修改。
?
根本的痛苦，并不在于一開始寫一份文檔，而在于所有寫下的文檔，都必須跟隨項目的進展而隨之變化。當(dāng)我們寫出來的文檔越多，需要被持續(xù)維護的文檔也就越多，需要反復(fù)檢查文檔間的可能存在的矛盾也就越多，所有扔出去的石頭，最后都會落回到自己頭上。
?
于是，還有不少項目組，將文檔工作與代碼工作截然分開，文檔就寫一次，用來應(yīng)付上面的管理層，而代碼自管自的繼續(xù)開發(fā)。對于小型項目來說，這其實是一個不錯的權(quán)宜之計。但是一旦項目越來越龐大、復(fù)雜。所有的隱性的知識，都僅僅存在于程序員的腦子里，所有成文的東西，都可能是錯的，而真實的情況，卻隱藏在代碼之中。如果代碼質(zhì)量再糟糕一些，后來維護的朋友，就遭遇火坑了。
?
文檔，寫還是不寫，這是一個問題！
?
還記得測試驅(qū)動開發(fā)嗎？為自己的每一個方法，每一個類，都寫出單元測試來。不但如此，更加徹底的做法是，在寫代碼之前，先寫測試用例。這樣才能保證不會忘記寫測試用例。更大的好處在于，這樣有助于思考、有助于獲得更加完善的設(shè)計，有助于寫出更加高質(zhì)量的代碼，有助于安全的重構(gòu)，有助于自動化的持續(xù)集成實踐。總之，是好得不能再好的一項開發(fā)實踐。
?
這一實踐之所以可行，就在于他將繁雜的集中的測試工作，分解為日常的，必須不斷進行的工作。當(dāng)你每天都在寫測試用例，當(dāng)你的每一個測試用例，都能夠與代碼完全對應(yīng)時，壓力反而減輕了，工作量也更少了，更重要的，一些優(yōu)良的習(xí)慣也因此被養(yǎng)成了。
?
在兩年前，我要開始一個全新的P2P網(wǎng)絡(luò)電視項目時，也在考慮關(guān)于文檔的問題。當(dāng)時我發(fā)現(xiàn)了Open Source的WikiPedia。這是一個PHP的WIKI，最大的應(yīng)用是維基百科全書。因此，這個項目的質(zhì)量就絕對值得信賴。我就將它拿過來，作為我們項目文檔管理的工具。
?
用Wiki來管理項目文檔，基于以下一些考慮：
文檔是項目的知識，這些知識必須集中管理、容易獲取、人人可以編輯。
項目在生長，代碼在增加，文檔也必須能夠跟隨項目自然生長，強行劃分設(shè)計階段和開發(fā)階段，是不可取的。
Wiki不是傳統(tǒng)的項目文檔，而是一個應(yīng)交流需要，可能隨時增刪改的知識庫。項目組的成員，遇到問題，就應(yīng)該首先查看Wiki，如果這是Wiki中沒有，那么他應(yīng)該找人詢問。而那個知道答案的人，如果他不想再今后不斷的回答同一問題，就應(yīng)該把這個答案寫入Wiki，這就是Wiki條目增長的自然動力。
傳統(tǒng)文檔最大的問題在于浪費，而Wiki通過持續(xù)修改，按需提供的方式，保證了所有寫下的文字，一定有超過一個人需要讀它。
?
在Wikipedia的基礎(chǔ)上，我又做了一些增強，以更好的輔助項目的管理。
Include功能，增加include標(biāo)簽，可以在一個條目中，引入其他條目的全文，而不是僅僅增加一個link。
文檔的層次結(jié)構(gòu)，當(dāng)項目的文檔條目逐漸增加，分門別類的條目，更加便于查找，也可以有效的避免條目重名的問題。
一個Click，就能夠創(chuàng)建新一個條目，用于填寫當(dāng)天的工作安排。
相應(yīng)的管理制度，也必須建立起來。
每日15分鐘文檔制度，基于“填寫當(dāng)日工作”的功能，我規(guī)定每個項目組成員，每天要花三個5分鐘來寫文檔，早上的5分鐘，填寫當(dāng)日工作計劃。中午的5分鐘填寫上午的工作情況，下班前的5分鐘，填寫下午的工作情況。這樣，每天的文檔工作相當(dāng)輕松，但是文檔能夠保證持續(xù)的跟隨項目成長下去。更進一步的，這樣的制度，對于項目的進度控制，也很有幫助。
User Case條目驅(qū)動，所有分解出去的User Case，在分配到責(zé)任人之后，該責(zé)任人的第一項工作，就是在Wiki中寫下對于這個User Case的理解。隨后項目進展，也應(yīng)該持續(xù)的維護這個條目。
同時進行Bug的管理，Bug也作為Wiki中的條目，以便于和其他條目項目引用。
每次Check In CVS時，必須寫注釋。這是更加細節(jié)的文檔，然后我還做了一個小程序，能夠自動的從CVSTrac中讀出當(dāng)天Check In代碼的注釋。供每個人在寫當(dāng)天文檔的時候引用。
總而言之，我對于項目文檔的看法，并不是非此即彼的極端主義者。在我看來，好的項目文檔管理政策，應(yīng)該有助于集中團隊知識和智慧，同時不要讓程序員痛苦和反感。這樣才叫做有效的項目管理。仿造Martin Fowler的著名文獻《持續(xù)集成》，我給這篇Blog起這樣一個名字《軟件開發(fā)文檔的持續(xù)集成》，希望能夠引發(fā)更多的、更深入的思考。
posted on 2006-05-12 14:23
讀書、思考、生活 閱讀(28652)
評論(3) 編輯 收藏