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

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

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

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

以80后小時候讀的連環(huán)畫為例，它就是優(yōu)秀文檔的典范。

像連環(huán)畫這樣優(yōu)秀的文檔，主要具備以下幾個特點：

1.長篇被分成小節(jié)。

2.小節(jié)中關(guān)鍵頁有圖。

3.描述言簡意賅。

4.頁數(shù)固定不多。

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

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

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

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

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

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

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

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


轉(zhuǎn)載自五四陳科學院[http://www.54chen.com]

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