程序文檔的重要性理解

也許在很多人眼中，程序文檔並沒有那麼重要，只要程序代碼能夠寫出來就OK了，尤其是在一些小公司，一個人做很多事，程序員很不願意寫文檔，甚至代碼的風格、規範也不是很顧忌。在剛來公司的時候，就接手了一些小模塊，由於沒有文檔，程序中也鮮有註釋，對其功能、原理、結構都不是很清楚，儘管量不是很大，還是看了好久才能夠熟練的維護和優化這些代碼。我雖然也不是計算機科班出生，但是對文檔的重要性還是比較清楚的，它們不僅對自己很重要，對整個開發團隊成員之間的合作也很重要。
就我個人而言，也不是開發文檔的忠實擁護者，但是我還是認爲適當的文檔會給程序的開發、理解、維護帶來很多好處，尤其是在團隊合作時。
首先，我認爲註釋即文檔，作爲一線程序員，往往對自己現在寫的代碼很熟悉，一看就知道什麼意思，但根據我自身的體驗，過了幾個月再來看，對於其中的關鍵部分或比較特別的代碼段，關於其原理和作用，已經模糊了。這時候，代碼當中的註釋就很有用了，例如在一個函數中，每隔幾行或重要部位，寫上幾句註釋，不管什麼時候來看，都知道當時爲什麼這樣寫，也便於後期的維護和優化。我就經常遇到這樣的事，過來很久來看以前的代碼和註釋，發現有另外一種很好的辦法來解決問題。同時，代碼註釋也能夠讓後來者能夠很好的理解代碼，開始工作。
另外，當自己開發比較大的項目或模塊時，如果輔以相關文檔，更能便於自己對項目或模塊的理解以及子模塊的組織和編寫。在實踐的過程中，我一般不會像寫項目需求文檔那樣寫很詳細的文檔，只會記載自己對項目或模塊的理解和解決思路，是一個很概要的東西，這個文檔可以讓自己加深理解，也可以給後來人關於這個項目的一個指導思想，而不是隻有密密麻麻的代碼。
文檔還有一個重要的作用就是團隊成員之間的交互和合作。我個人而言，在給同事提供一個C++頭文件時，一定會附上一個詳細的接口說明文檔，包括接口的作用、參數的意義、返回的結果等。在這裏，我是服務提供者，同事就是消費者，爲我的同事提供一個詳細的說明文檔，能夠節省後續開發過程中很多不必要的解釋和爭論。有的時候我作爲消費者和同事合作時，僅僅得到一個頭文件和一個動態庫，沒有任何說明，然後我在每次要調用一個函數或使用一個類接口時，都要去問一下這個怎麼用，參數怎麼傳遞等，浪費了很多時間，也再不斷消耗同事的耐心，因爲我不可能根據這個函數原型就能瞭解他的使用，並寫出可靠的代碼來。
作爲一個有幾年經驗的程序員，我從始至終都很關注我的代碼風格、編程規範、註釋、文檔，我覺得這不僅沒有浪費多少時間，還給我提供了很多幫助，節省了很多時間。