可用的軟體 重於 詳盡的文件

這是不是就是代表我們不需要寫文件呢?
生為程序員出生的我,我其實蠻喜歡這句話的,如果能夠不寫文件,那該有多好.

不過我們先來瞭解一下,寫文件的目的是什麼?

• 以程序員來說,他寫的文件的目的就是希望其他的人知道怎麼用這個類別或是這個函數,所以他需要寫文件
• 以 PO/PM 的角度來說,寫文件的目的有兩個,一個是跟客戶確認需求的需求文件,另一各式跟程序員溝通的規格文件
• 以使用者的角度來看,他需要使用文件來知道怎麼使用這個產品,所以他需要一個文件

不曉得大家有沒有發現這三個文件有一個共通的地方,那就是一方跟另一方說你要怎麼使用我的東西,或是我想要的東西是什麼
所以基本上文件的目的是溝通

雖然文件並不是一個有效的溝通方法,最有效的溝通方法是面對面拿著紙和筆當面溝通

但文件可以解決無法面對面溝通的問題,所以文件有些時候是不可或缺的,

以程序員的例子來說,他希望別人知道如何使用他所寫的類別,如何使用他所寫的函數,所以他寫了一個使用說明文件或是個註解.
但這個文件真的是必要的嗎?如果你聽過Clean Code,你可能會有不同的想法.
在 Clean Code 的世界裡,文件不是必須的,
你想想為什麼你需要寫文件來說明你的程式?
如果你的程式碼能夠自己解釋他自己,讓別人一看就懂,那還需要而外的說明嗎?
再者,為程式碼寫說明或註解,常常會因為程式碼改了但文件或註解沒改,對使用他的人造成了困擾,此時有寫可能比沒寫還要慘
所以比較好的作法就是讓程式碼能夠自我解釋及說明增加可讀性,以便所寫的程式別人易於理解,如此一來就不需要寫說明文件或註解了.

另一個方面,程序員也希望透過寫說明文件來讓別人知道如何使用他的函數,所以他必須寫文件.
同樣的,也會有不一致的情況發生.
這邊比較好的做法是,為你的程式寫測試,如此一來別人就知道你的程式有支援哪些功能,當要使用某功能時應該怎麼呼叫.
如果哪天你修改了程式碼,如果造成你的測試程式出錯了,你也會跟著修改,防止說明文件和程式碼不一致的情況發生.
所以好的程式碼使用說明文件就是測試,因此如何增加測試程式的可讀性就變成了一個很重要的課題.