我們?nèi)绾伍_始對項目進(jìn)行管理：文檔很重要
我們需要哪些文檔，工具和努力
軟件項目肯定離不了文檔和管理工具，如果您的項目還沒有它們，那么請從現(xiàn)在開始。那么文檔是不是越多越好呢？老話說的好，合適的才是最好的。小而精的文檔和工具會讓我們事半功倍，大而全的文檔會讓我們疲于奔命，最后迷失在文檔的海洋中。
51CTO向您推薦上一篇系列文章：《我們?nèi)绾伍_始對項目進(jìn)行管理：需要什么樣的人》
我們寫代碼的都知道，錯誤的注釋比沒有注釋更可怕；同樣的，沒有及時得到更新的文檔比沒有文檔更可怕，因為文檔就是項目的注釋。那么我們是否有必要去更新那些我們根本沒有用到的文檔呢？很顯然，那是非常沒有必要的，是對資源的浪費。文檔說起來其實就是一個工具，是一個讓我們開發(fā)時有依據(jù)，可以追溯開發(fā)過程以及記錄開發(fā)結(jié)果的工具。我們只有用到它，它才有存在的必要。
那么文檔過于少或者干脆沒有文檔，不是更簡潔？我想說：不寫代碼不是更簡潔？玩笑歸玩笑，沒有文檔或者文檔太少會導(dǎo)致的問題大家可能也都遇到過：那就是過程不可追溯，有些非常重要的邏輯沒有記錄，需要用到時團(tuán)隊成員各執(zhí)一詞，甚至需要重新找客戶確認(rèn)而是客戶認(rèn)為我們不夠?qū)I(yè)；有些非常重要的設(shè)計沒有記錄，導(dǎo)致代碼維護(hù)困難，以至于維護(hù)人員破口大罵開發(fā)人員寫的什么垃圾代碼做的什么垃圾設(shè)計。有些設(shè)計非常的巧妙，非常的值得學(xué)習(xí)，然而就是因為沒有留下記錄而被初學(xué)者如我一樣的人罵了N次。在反省自己不夠聰明時，是否也該讓寫代碼的人反省一下為什么沒能留下點兒記錄？
有一種觀點是最好的設(shè)計就是代碼，意思是代碼就是設(shè)計，代碼應(yīng)該非常的優(yōu)秀，可讀性特別好，讓人一看就明白，我完全同意。如果代碼寫到這種程度，那文檔就真的沒用了。那么請自問，您是這樣嗎？如果是，沒文檔，沒問題；如果不是，請把重要的東西寫下來。那么，哪些是重要的呢？
哪些是必須的， 哪些是Optional的。對于哪些文檔更重要些，應(yīng)該由項目的具體情況而定，特別是項目的大小，邏輯的復(fù)雜程度，人員的情況等等很多因素。在我做過的項目中，我個人認(rèn)為最重要的一些文檔和工具如下所述：
1， 功能說明書（Functional Specification）------按獨立功能劃分優(yōu)先級，每一條記錄都是一個可交付物，都是一個功能。整個文檔就描述了整個項目的交付功能和優(yōu)先級。項目中的所有人，都應(yīng)該關(guān)注這個文檔：測試用它來寫測試用例；開發(fā)人員用它來決定先開發(fā)哪個功能；PM用它來查看功能的完成和驗證狀態(tài)。它通常不應(yīng)該內(nèi)容過多（由項目規(guī)模決定），我覺得最多兩行字就可以描述一個獨立工作的功能，至于對這個功能的理解，應(yīng)該由負(fù)責(zé)它的程序員來完成。
2， 核心流程圖。這個流程圖可能描述了用戶使用該系統(tǒng)的過程；也可能描述系統(tǒng)中數(shù)據(jù)的流轉(zhuǎn)；也可能描述表單的流轉(zhuǎn)。總之，它描述一個過程，這個過程對用戶來說非常重要。這個圖有時候也會被其它的圖，如順序圖代替。
3， 部署文檔。該文檔描述了該系統(tǒng)應(yīng)該如何部署，它不一定非要是一個word文檔，也可能僅是一個bat文件而已。這個文檔應(yīng)該描述該項目如何部署，步驟是怎么樣的，需要哪些文件，需要哪些硬件支持，以及需要注意什么。部署歷來都不太被重視，大家覺得只要東西做出來了，部署不就是放上去嗎？其實不然。在經(jīng)歷了一定周期的開發(fā)后，開發(fā)過程中積累的配置，對環(huán)境的要求，在真正部署的時候很多就忘了，所以部署可能會花費很多沒必要的時間，我覺得這也是微軟要做daily build的原因之一，每天都build一個可用的版本，當(dāng)然部署就沒有問題了。我們剛開始可能不需要每天都build一個版本，但最少要一周或者兩周部署一個版本吧。每次部署都整理一個自動化的腳本或者文檔，會讓你最后上線的時候非常的從容。
4， 測試用例。我不是一個測試人員，測試也是我覺得一直沒有做到位的地方。客觀的說，我覺得用例應(yīng)該花很大心思去編寫，就像用戶真正的在使用軟件一樣。項目應(yīng)該在設(shè)計和開發(fā)的時候就以滿足用例為目標(biāo)，而不是開發(fā)完了才想起來用例，去測試，發(fā)現(xiàn)問題再修改，回頭想想，這可能就是測試驅(qū)動開發(fā)產(chǎn)生的原因吧。我們知道用戶發(fā)現(xiàn)錯誤修改的成本高于我們自己發(fā)現(xiàn)的錯誤；同樣的，設(shè)計和開發(fā)階段就解決的問題成本也遠(yuǎn)遠(yuǎn)小于測試階段發(fā)現(xiàn)的。正是，問題發(fā)現(xiàn)的越早，解決起來就越容易，成本就越低。
5， Bug管理工具。這個管理工具可以是一個excel，當(dāng)然，我并不推薦這么做，畢竟excel卻是不那么自動化。但是，只要比excel自動化一點點兒的信息系統(tǒng)就可以了，它需要可以記錄問題，可以傳截圖，這就夠了。我推薦使用bug tracker，這是個dotnet開發(fā)的開源的bug管理工具，其實也可以管理需求，是非常實用的。
以上五個是我認(rèn)為最重要的，我覺得是項目開始進(jìn)行管理的階段必不可少的；而下面幾個，則是大家視情況可選的。
6， 核心類圖。這個可能是可選的，因為有時候，類的關(guān)于沒那么復(fù)雜，也就沒有必要有這個圖；相反，則需要進(jìn)行記錄。
7， 數(shù)據(jù)庫設(shè)計。數(shù)據(jù)庫設(shè)計文檔可能在review的時候用到。
8， 系統(tǒng)間接口圖。如果產(chǎn)品有若干個子系統(tǒng)，如web service等等，那么我認(rèn)為需要一個描述系統(tǒng)間接口和交互關(guān)系的圖，這個圖應(yīng)該在設(shè)計的早期就開發(fā)出來供大家使用并且隨時保持更新和關(guān)注。
有了文檔和工具，是不是就一切OK了呢？不對，就像大而全的文檔并不能幫助我們成功一樣，有了文檔并不代表項目就能成功，如何維護(hù)和使用這些文檔和工具是相當(dāng)重要的。每個文檔都應(yīng)該有人去維護(hù)，那么誰去做這個事呢？我認(rèn)為項目經(jīng)理應(yīng)該經(jīng)常拿著功能說明書開會，它也可以被看做是WBS的初級版本，可以被標(biāo)注狀態(tài)和優(yōu)先級；所有人都應(yīng)該熟悉流程圖，并隨時提出對流程圖進(jìn)行檢驗和review；應(yīng)該指定一個人負(fù)責(zé)構(gòu)建，這并不需要花費很多時間，但是需要細(xì)心和一些完美主義精神；測試人員自然要維護(hù)好測試用例；每個人特別是開發(fā)人員，都應(yīng)該有一種覺悟，那就是一旦想起了哪些重要的邏輯，不管是業(yè)務(wù)的邏輯還是系統(tǒng)的算法，都應(yīng)該記錄到bug管理工具上。Bug管理工具完全可以記錄這些零散但卻重要的東西，以便將來方便查詢。
在這里我也是根據(jù)自己的經(jīng)歷簡單的談了一些我的看法，這并不是金科玉律，我還得說，合適你的才是最好的。
（四） 代碼規(guī)范的選擇
做開發(fā)不可避免的遇到代碼規(guī)范，從上學(xué)時就會學(xué)習(xí)到一些規(guī)范，但是每個公司都不同，那么我們到底要遵守哪些規(guī)范呢？我個人認(rèn)為，一個合格的程序員應(yīng)該可以隨時調(diào)整自己適應(yīng)任何一種規(guī)范，這是一種職業(yè)素養(yǎng)和能力。而何時該遵循何種規(guī)范，這也有一定的原則。
1， 在現(xiàn)有系統(tǒng)（代碼）基礎(chǔ)上進(jìn)行開發(fā)。這種情況下，我們應(yīng)該盡量的去遵循原有系統(tǒng)的規(guī)范，不論是命名還是注釋。因為如果這時你非要按照自己的習(xí)慣寫，那么系統(tǒng)就會出現(xiàn)兩種完全不同風(fēng)格的代碼，這對將來的維護(hù)是一種噩夢。但是，遵循原有規(guī)范不是遷就原有錯誤。如果發(fā)現(xiàn)原有的規(guī)范會造成一定的問題，就要立刻改正，不能裝傻充愣假裝看不見。
2， 新建團(tuán)隊開發(fā)新的系統(tǒng)。新建的團(tuán)隊中團(tuán)隊成員可能來自不同的環(huán)境，對規(guī)范的選擇傾向一定是不完全一樣的，此時要怎么做呢？這時，項目的領(lǐng)導(dǎo)者應(yīng)該組織大家一起做一個決定，討論如何定義變量，如何給控件取名等等。在出現(xiàn)意見不統(tǒng)一又誰都說服不了誰的情況時，項目經(jīng)理應(yīng)該做出明確的決定。此時選擇一種規(guī)范遠(yuǎn)比同時遷就兩個人要來的好，不然造成新系統(tǒng)中存在兩種規(guī)范，同樣是維護(hù)的噩夢。
3， 穩(wěn)定團(tuán)隊開發(fā)新的系統(tǒng)。這種情況就容易得多，團(tuán)隊穩(wěn)定后團(tuán)隊成員漸漸的了解了互相的習(xí)慣，互相學(xué)習(xí)后就更容易達(dá)成妥協(xié)。只要注意讓新加入的成員適應(yīng)就可以了。
有人可能覺得代碼規(guī)范沒什么大不了，功能正確沒有bug不就行了？當(dāng)然，如果沒有bug那肯定沒問題，然而一個系統(tǒng)運行到退休還沒有bug，哪位見過呢？我做了一些運維工作之后才漸漸了解到，不同風(fēng)格的代碼讀起來就像是一會兒在赤道，一會兒在南極，非常的痛苦，有時甚至?xí)斐上到y(tǒng)很多的不一致，大大增加了維護(hù)的工作量。我們的目標(biāo)之一不就是增加系統(tǒng)的可維護(hù)性嗎？
原文鏈接：http://www.cnblogs.com/GodSpeed/archive/2011/06/08/2074948.html
【編輯推薦】
