大部分的程序員都認為：所有不能直接產(chǎn)出代碼的事情都是沒有意義的。思考并不能直接轉(zhuǎn)換成代碼，但是倘若在沒有一個整體框架之前，就開始匆忙碼字，這也是沒有意義的。在程序員開始寫代碼之前，他們應(yīng)該先充分理解這些代碼終所要實現(xiàn)的功能。理解的過程，自然需要去思考，而將思考過程寫下來，對于程序員來說又是件很耗時的事兒。
如果說建筑師后的成品是建筑的話，那么程序員和軟件工程師終的成品就是軟件。在實際動工之前，建筑師將會將建筑的每一個細節(jié)，都在藍圖上加以呈現(xiàn)。只是程序員和軟件工程師并不會這么做?；蛟S，這就是為什么房子很少倒塌，而軟件卻經(jīng)常崩潰的原因？
設(shè)計藍圖會幫助建筑師確定他們的設(shè)計是可行的。“可行”并非只是保證不倒塌，它同時還意味著，建筑能夠達到預(yù)定的服務(wù)于人的目標?？蛻艋蛘唛_發(fā)商，也是通過藍圖去了解一個設(shè)計師的想法和他正打算去做的事情。
相較之下，很少有程序員會在他們開始寫代碼之前，連一個粗略的框架都沒有。
但漫畫家 Dick Guindon 曾經(jīng)說過：寫作是發(fā)現(xiàn)你想法有多糟糕好的方式。
藍圖幫助我們理解建筑的構(gòu)架，同樣，在我們開始噼里啪啦寫代碼之前，我們也需要一個類似的“藍圖”，也就是“注釋”(specification)。
“注釋”不能直接產(chǎn)出代碼，所以被很多程序員忽視。但沒有“注釋”，直接開寫，就好像讓建筑承包商沒有設(shè)計師的圖紙就直接上陣一樣。
也有人會說，將程序員和建筑師類比，并不合理。因為拆墻重建困難，但刪掉重寫則相對容易，所以，程序員可以先寫著，不滿意再改。
這種想法是錯的。為什么呢？因為 Debug 的過程也非常耗時。
我近也完善了一些程序，這個過程需要對程序構(gòu)架本身有個非常清晰的了解。我花了接近一天的時間去了解整個程序的運作機制，而倘若有注釋的話，這可能只需要 5 分鐘的時間。
為了避免引入 bug，我需要理解任何小的調(diào)整可能帶來的結(jié)果。而沒有注釋，使得我必須花很長時間了解每條代碼的含義和作用。尤其對于上千行的代碼來說，首先讀懂它就很耗時，想要改掉其中的某行，我必須了解小的調(diào)整可能對整體架構(gòu)和前后邏輯造成的影響。終，在超過一個星期的時間里我只改了 180 行代碼，而這對一個動輒千行的程序來說，改變算是很小的了。
Debug 只是寫代碼一個小的組成部分。這數(shù)千行的代碼很多我 10 年前寫的，盡管我對它們?nèi)杂行┰S殘存的記憶，但如果有注釋的話，修改代碼的過程會更加順暢，我不僅能在短的時間里讀懂整個框架，還可以準確定位我所要修改的部分。
改別人的代碼就更加困難了，每個人的思維方式都不一樣，如果沒有注釋，我通常要花費兩倍以上的時間，只是為了修改一些細小的錯誤。
那么，我所謂的“注釋”又是指什么呢？“注釋”是指附在代碼之后的，一段形式化規(guī)范說明的文字。但需要區(qū)分開的是，如果只是去打造一個工具室，我們是不需要一整套摩天大樓藍圖的，同樣，對于小的算法來說，我們也不需要給每條代碼加上注解。
我近要編寫的程序，多稱得上是“平房”，而非摩天大樓。我會為我的每個算法附上注釋，有些非常簡單的算法，我通常只會插上一兩句注解。我有一個非常簡單的法則來幫助我和其他人了解我的程序：注釋應(yīng)該盡可能有效地去幫助任何一個人理解和使用我的代碼。
一旦我知道一行特定代碼要做的事情后，寫的過程其實是非常簡單而直接的。也有些程序需要用到非常規(guī)算法，這時我會寫下我算法的主要思路，來試探其可行性，同時也幫助我更高效的 Debug。
除了那些特別重要的代碼，通常我的注釋都是非正式的。在過去的十年里，需要我寫準確并正式注釋的次數(shù)并不多。但對于一個非常復(fù)雜的系統(tǒng)來說，注釋的重要性不言自明。很少有工程師會在構(gòu)建一個復(fù)雜系統(tǒng)時，花時間去寫好注釋。有些學(xué)校也會教你怎么寫注釋，但更多時候都是教你如何寫好代碼。這需要實踐，如果你沒有畫過搭建一座平房的圖紙，你很難直接畫出摩天大樓的藍圖。
寫好注釋也沒有一個簡單的準則，但有一點你要盡量避免，那就是用代碼去解釋代碼。就好像你不能用兩個人們都不理解的東西，用其中一個去解釋另外一個。建筑師也不能直接用磚塊來告訴你，他想搭建一個什么樣的房子。
了解一個復(fù)雜的系統(tǒng)，好的辦法就是將其核心用簡單的概念，抽象的概括出來。初中數(shù)學(xué)的一些基本概念可以用來幫助你寫好注釋，比如你可以用一些集合、方程和簡單的邏輯來解釋你的代碼。對于一些復(fù)雜的算法，你也可以引入數(shù)學(xué)里沒有過的概念來加以解釋?？偟膩碚f，如果你的注釋偏離一些抽象的數(shù)學(xué)基本概念越遠，理解起來也就越困難。
