文所以載道也。  —— 宋·周敦頤《通書(shū)·文辭》

對(duì)于我們程序員來(lái)說(shuō)，我們的工作也是寫(xiě)作——幾乎每天都要寫(xiě)代碼；而且還要載“道”，不僅僅要滿(mǎn)足客戶(hù)的需求，還要讓代碼具有高度的可讀性，這樣其他的程序員可以更容易地對(duì)代碼進(jìn)行修改和擴(kuò)展。

按這樣的要求，我們需要為代碼編寫(xiě)足夠的文檔，也就是將代碼“文檔化”。常見(jiàn)的做法有兩種，外部文檔和注釋。

外部文檔

外部文檔指的是在代碼文件之外編寫(xiě)的附加文檔，比如在Word文檔中采用大量的篇幅（如UML圖、表格）來(lái)設(shè)計(jì)或記錄相關(guān)的包、類(lèi)型、類(lèi)型成員、成員參數(shù)之類(lèi)的信息。這看起來(lái)很規(guī)范，但如果你用過(guò)這種方式，一定會(huì)討厭它。這種方式的主要問(wèn)題在于：

1）增加很多額外的工作：編寫(xiě)代碼本身的壓力已經(jīng)很大，在壓力之下，我們往往選擇做那些最必需的事情，就是實(shí)現(xiàn)功能，如果時(shí)間緊急，編寫(xiě)文檔就可能是草草了事了。

2）文檔需要與代碼保持同步：即使你在開(kāi)始認(rèn)真編寫(xiě)了文檔，后來(lái)代碼有了修改和擴(kuò)展（這是不可避免的，即使采用所謂的凍結(jié)需求），那么文檔就需要更新，否則就會(huì)提供誤導(dǎo)信息。

3）大量的文檔難以管理：如果代碼量較大，那么本身就需要大量的文檔；同時(shí)文檔也需要進(jìn)行版本管理，那么就產(chǎn)生了不同版本的文檔；另外這些文檔基本上是一些簡(jiǎn)單的文本。如此一來(lái)，要在這些文檔中找到所需的信息，難上加難。

文檔具有這些問(wèn)題，一個(gè)重要的原因是，它們離代碼太“遠(yuǎn)”了。我們可以將它們搬到代碼文件里面，這就是第二種做法：注釋。

注釋

程序員對(duì)文檔往往比較抵觸，對(duì)注釋的態(tài)度就溫和多了，甚至相當(dāng)一部分人支持編寫(xiě)大量的注釋。的確，如果在IDE中看到分布合理的綠色代碼塊（注釋文本的常見(jiàn)顏色），人們會(huì)感覺(jué)比較舒服，如果滿(mǎn)屏幕全是代碼，心里不免會(huì)犯怵。

從語(yǔ)法的角度來(lái)看，注釋就是編譯器將忽略不計(jì)的源代碼塊。所以，在這里你想寫(xiě)什么就寫(xiě)什么。

從語(yǔ)義的角度來(lái)看，注釋是昏暗泥濘的小路和明亮通暢的大道之間的區(qū)別。注釋是對(duì)其所處位置的代碼的解釋?zhuān)梢詮?qiáng)調(diào)某些特定問(wèn)題、描述某個(gè)復(fù)雜算法、對(duì)代碼進(jìn)行合理分隔、協(xié)助進(jìn)行維護(hù)的程序員（這個(gè)人有可能是你自己）。由此可把注釋看作是代碼的一種“內(nèi)部文檔”。

那是不是就需要大量的注釋呢？至少我們?cè)?jīng)被這樣教導(dǎo)過(guò)，但事實(shí)并非如此。不知道你的習(xí)慣怎樣，我在閱讀代碼的時(shí)候，看到注釋一般會(huì)先看注釋?zhuān)以?strong>假定這些注釋對(duì)代碼提供了附加的價(jià)值。但我發(fā)現(xiàn)，注釋往往很隨意，甚至有可能誤導(dǎo)別人。你可以說(shuō)，這是注釋編寫(xiě)者的問(wèn)題，注釋是無(wú)辜的，但必須承認(rèn)的是，注釋比代碼更容易說(shuō)謊。究其原因，注釋雖然離代碼很近，但仍然是一種文檔，它具有與外部文檔類(lèi)似的問(wèn)題：

1）增加很多額外的工作

2）需要與代碼保持同步

3）大量的注釋可能會(huì)妨礙代碼的閱讀：注釋在那里，人們不能置之不理，如果注釋太多就成阻礙了。《重構(gòu)》一書(shū)認(rèn)為注釋過(guò)多是一種“壞味道”。

看來(lái)，注釋也有不少問(wèn)題，它們離代碼仍有距離。能否將“文檔”與代碼的距離再拉近一點(diǎn)？那該怎么做？

先來(lái)考慮我們?yōu)槭裁匆砑幼⑨尅＿@往往是因?yàn)榇a本身不容易讓人看懂，也就是說(shuō)代碼的意圖和表現(xiàn)有距離，所以才需要使用注釋。如果能夠做到讓代碼本身就體現(xiàn)出意圖，是不是就不需要注釋了？這種方式就是本文的主題：代碼的自文檔化。（需要注意的是，自文檔化能夠取代大多數(shù)的注釋?zhuān)⒉荒?00%取代）

什么是代碼的自文檔化（Self Documenting Code）？

唯一能完整并正確地描述代碼的文檔時(shí)代碼本身，通常情況下，這也是你能獲得的唯一文檔。因此，我們應(yīng)當(dāng)努力使代碼成為良好的文檔，一種人人可以讀懂的文檔。這也就是通常所說(shuō)的良好的可讀性，做到了這一點(diǎn)，犯錯(cuò)的可能性就降低了，同時(shí)代碼的維護(hù)成本也降低了——人們不需要花太多時(shí)間去熟悉你的代碼。（更多信息，可以參考Ward Cunningham的wiki）

代碼自文檔化的技巧

我們可以采用多種方式來(lái)提高代碼的可讀性。其中一些技巧是非常基礎(chǔ)的，我們?cè)诰幊讨跻褜W(xué)習(xí)過(guò)，而有些則更為巧妙。這里首先給出兩個(gè)例子，加深一下你對(duì)代碼可讀性好壞的印象。

NET技術(shù)：編寫(xiě)自文檔化的代碼，轉(zhuǎn)載需保留來(lái)源！

鄭重聲明：本文版權(quán)歸原作者所有，轉(zhuǎn)載文章僅為傳播更多信息之目的，如作者信息標(biāo)記有誤，請(qǐng)第一時(shí)間聯(lián)系我們修改或刪除，多謝。