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