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

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

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

外部文檔

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

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

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

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

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

注釋

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

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

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

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

1）增加很多額外的工作

2）需要與代碼保持同步

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

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

先來考慮我們為什么要添加注釋。這往往是因為代碼本身不容易讓人看懂，也就是說代碼的意圖和表現有距離，所以才需要使用注釋。如果能夠做到讓代碼本身就體現出意圖，是不是就不需要注釋了？這種方式就是本文的主題：代碼的自文檔化。（需要注意的是，自文檔化能夠取代大多數的注釋，但并不能100%取代）

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

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

代碼自文檔化的技巧

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

NET技術：編寫自文檔化的代碼，轉載需保留來源！

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