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