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

對于我們程序員來說，我們的工作也是寫作——幾乎每天都要寫代碼；而且還要載“道”，不僅僅要滿足客戶的需求，還要讓代碼具有高度的可讀性，這樣其他的程序員可以更容易地對代碼進行修改和擴展。

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

外部文檔

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

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

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

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

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

注釋

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

從語法的角度來看，注釋就是編譯器將忽略不計的源代碼塊。所以，在這里你想寫什么就寫什么。

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

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

1）增加很多額外的工作

2）需要與代碼保持同步

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

看來，注釋也有不少問題，它們離代碼仍有距離。能否將“文檔”與代碼的距離再拉近一點？那該怎么做？

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

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

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

代碼自文檔化的技巧

我們可以采用多種方式來提高代碼的可讀性。其中一些技巧是非常基礎(chǔ)的，我們在編程之初已學(xué)習(xí)過，而有些則更為巧妙。這里首先給出兩個例子，加深一下你對代碼可讀性好壞的印象。

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

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