一、什么樣的文檔（代碼）叫做“好”？

任何一篇文檔，目標都是給別人看懂。

任何一段代碼，首先也都是別人能看爽了才是目標。

以上述“世界觀”為準，很容易得到文檔（代碼）好不好的結論。

以80后小時候讀的連環畫為例，它就是優秀文檔的典范。

像連環畫這樣優秀的文檔，主要具備以下幾個特點：

1.長篇被分成小節。

2.小節中關鍵頁有圖。

3.描述言簡意賅。

4.頁數固定不多。

典型地，如果在寫文檔（代碼）時，能夠做到上述四點，都是優秀的。
比如：
PHP文檔造福了多少PHP程序員，讓PHP這門語言流芳百世、追隨者眾多。在PHP文檔中，每一小節都進行了特別歸類; 在關鍵位置還有不少例子代碼; 每個方法的作用也是言簡意賅; 每一小節的數量都不是很多。

再來看nginx代碼，完全是一個大型服務端軟件構建的一個范例。只看src目錄中的源碼，從一開始就分成了core、event、http、mail、misc、os，這樣相當清晰明了的層級結構和定義，讓后續很多事情方便擴展; 每一部分的代碼都能夠讓讀者一眼看明白是做什么的; 每個細節的方法長度也不是特別長; 每個分類里的內容也相對是固定的，后續的改進都是在plugin上比較多。

二、幾種實際的土辦法提高文檔（代碼）能力
在上述建立好了對好文檔（好代碼）的世界觀之后，下面再分享一些總結出來的套路，如果前面世界觀沒理解透，只把這里的土辦法理解了，也能寫出來容易讀的文檔（代碼）。

辦法一、寫文檔先寫段落標題，寫代碼先建分類目錄（java叫做package）。
在一切開始之前，如果無法下筆，則先想想要寫代碼架子都有哪些。

辦法二、一級段落不要超過5個。
這純粹是個經驗值，實際超過3個的時候已經開始有些遺忘前面的了。套在代碼上，不要超過5種主要功能的目錄，像nginx有6個，不過os和misc基本上都是固定不改的東西，所以常動的也只有4個而已。

辦法三、不要沒有段落畫大餅
這和辦法二是相反的，因為人腦對內容的吸收是有階梯的，越往后的內容越難記住。所以在適當的時候要歇一歇。套在代碼上，就是不要搞一個大類，什么都能干。

辦法四、盡可能讓文檔（代碼）先少后多
這個辦法是指，讓讀代碼的人先看一小部分，慢慢再“勾引”讀者不斷地深入。

好了，上面的辦法都實施之后，一手好濕就應該不遠了。


轉載自五四陳科學院[http://www.54chen.com]

如何寫一手好文檔(好代碼)?