怪怪談注釋

閒話不說，本篇主要討論注釋的非必要性。

以我個人的經歷來說：從滿篇清晰工整的注釋到一字未寫的（過於玩具的不提，只談那些邏輯複雜或者職責分配分散的），上至大牛神作下至身邊比community server寫的還亂的，我從沒看過注釋。

另一方面，說實話，雖然很多人b4我這樣的，但是我仍然要恬不知恥地說，我也基本不寫注釋；而過去在作為乙個管理者的角色時，我從來不要求別人寫注釋。什麼叫做「基本」呢？

就是說以下兩種情況例外：

1. 一句或一段**抽象過了頭，也許需要跟業務相關的描述建立乙個直觀的對應。

2. 因為安排的不夠妥帖或者很難妥帖，一段邏輯中蹦出一句為不相關邏輯服務的**。

而這兩種情況出現的極少。

但是可以想象，乙個比我接觸過的環境更加趕鴨子上架的環境，如果沒有把設計和**整理好的時間，也必然沒有做注釋的時間。很多人否認這一點，認為加幾句話自己以後看也清楚，費什麼功夫。

不是這樣。

在頭腦發熱的時候，大多數人只想抓住自己當時稍縱即逝的靈感（無論在哪個水平上），他腦子裡怎麼想的在當時是非常明白的，而5分鐘後就未必了。這時他確實應該整理思路，可list上卻有其它更重要的事情。

那麼我的觀點是什麼呢？

要麼組織上並不存在資源（時間、人力）不足的情況，這時大多數設計和實現因為足夠好而無需注釋；要麼就根本沒時間寫注釋。這絕對不是作者的錯，有時甚至不是組織的；尤其從作者的角度來看，根本沒轍。

唯一的辦法就是不斷增加閱讀**的水平、理解業務邏輯的水平。這兩個能力獲取的資訊相互印證，一點一點往前走。組織沒提供給你足夠時間怎麼辦？那不是你的錯，也不必為此有愧疚或憤怒，咱也是沒轍。

那麼什麼時候也不需要注釋和文件嗎？不是，比如庫作者必須寫明介面如何使用就是一例。但在這個之前，首要的一點是，盡量不要設計的讓人深入庫原始碼才能得心應手；需要說明的是，庫是如此，而框架卻很難做到這樣。

也正是庫和框架的區別，導致gof中其中乙個在若干年後放棄了框架式的設計。但是大家都有反射asp.net原始碼的經歷：至少從我個人來說，即使對它的設計頗有意見，但也從來沒有產生「要是有注釋就好了」的念頭。

合格的程式才是我們想要的，而不是注釋。不合格的程式往往也就意味著連寫注釋的條件都沒有：即使不是因為當時的具體情況，而僅僅是因為組織僱傭了乙個水平低下且不負責任的人，這也是乙個資源問題。

大家知道我很少說人情世故，上面這些話也不是從這個角度分析。

不過有一點，沒有什麼是我們能要求別人的。我們是擦屁股的人的時候，我們要知道社會認可了那個留下便便的；我們是管理者的時候，我們應該想辦法為組織爭取更多的資源，這是管理者的乙個職責和義務所在。

是不是所有情況下都如此惡劣？當然不是。

比如就一些公司所針對的業務來說，可以以很低的成本就形成越來越多的約定和約束，讓程式設計師可以自由發揮的餘地越來越小。但這個過程主要是自上而下的，而本篇的目的是給任何水平層面上「不寫注釋」的程式設計師說兩句，就不多關注了。

沒辦法的時候呢？只能聽天由命了。

p.s. 很多大牛甚至喊出了「注釋是有害的」這樣的口號；如此看來，我還是不夠激進了，慚愧。

注釋一：

什麼叫更重要的事情？就是說，已經完成的**做的再完美、文件在齊全，下面這件事不做或做不完，整個專案也會死。

一次完善也許可以說不算什麼，但是誰寫程式能夠只有一處需要完善呢？我們要明白的是，當我們為幾處生氣的時候，這僅僅意味著我們只見到了這幾處。

這樣的**即使不能說值得表揚，但針對具體情況，也許已經不錯了：此人當時在其他更必要的地方花費的心血是我們沒能體會的。

如果處處都讓人生氣，這就一定是乙個非常嚴重的資源問題，不屬於程式設計師這個層次，不再贅言。

注釋二：

有人可能會說了，你別操蛋了，哦，至少夠我寫注釋的時間，就不夠那孫子了？三點：

1. 你面臨的情況不同。人無法兩次進入同一條河流，這點沒法真正徹底的反駁。

2. 你水平比較高，也不過是因為組織掌握資源的狀態和能力發生了變化；沒人應該因為水平低挨罵。

3. 重申一遍個人觀點，如果乙個人真有足夠的時間寫清晰的、很難讓任何人誤解的注釋，他應該把這個時間花在**上。

多說一句的是，我並不是在說存在即是reasonable，具體問題具體分析。