寫代碼和寫文章，從某種程度上是相通的，需要邏輯、構(gòu)架，也要盡可能的簡(jiǎn)練。我們之前說過，創(chuàng)作者的時(shí)間表和管理者的時(shí)間表是不一樣的，編代碼和寫文章，都是一個(gè)孤獨(dú)而不能受到干擾的過程，面對(duì)屏幕，就是一場(chǎng)自己與自己的戰(zhàn)爭(zhēng)。

同樣，如果說建筑師***的成品是建筑的話，那么程序員和軟件工程師最終的成品就是軟件。在實(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)?？蛻艋蛘唛_發(fā)商，也是通過藍(lán)圖去了解一個(gè)設(shè)計(jì)師的想法和他正打算去做的事情。

相較之下，很少有程序員會(huì)在他們開始寫代碼之前，連一個(gè)粗略的框架都沒有。

大部分的程序員都認(rèn)為：所有不能直接產(chǎn)出代碼的事情都是沒有意義的。思考并不能直接轉(zhuǎn)換成代碼，但是倘若在沒有一個(gè)整體框架之前，就開始匆忙碼字，這也是沒有意義的。在程序員開始寫代碼之前，他們應(yīng)該先充分理解這些代碼最終所要實(shí)現(xiàn)的功能。理解的過程，自然需要去思考，而將思考過程寫下來，對(duì)于程序員來說又是件很耗時(shí)的事兒。

但漫畫家 Dick Guindon 曾經(jīng)所過：

藍(lán)圖幫助我們理解建筑的構(gòu)架，同樣，在我們開始噼里啪啦寫代碼之前，我們也需要一個(gè)類似的“藍(lán)圖”，也就是“注釋”(specification)。

“注釋”不能直接產(chǎn)出代碼，所以被很多程序員忽視。但沒有“注釋”，直接開寫，就好像讓建筑承包商沒有設(shè)計(jì)師的圖紙就直接上陣一樣。

也有人會(huì)說，將程序員和建筑師類比，并不合理。因?yàn)椴饓χ亟ɡщy，但刪掉重寫則相對(duì)容易，所以，程序員可以先寫著，不滿意再改。

這種想法是錯(cuò)的。為什么呢？因?yàn)?Debug 的過程也非常耗時(shí)。

我最近也完善了一些程序，這個(gè)過程需要對(duì)程序構(gòu)架本身有個(gè)非常清晰的了解。我花了接近一天的時(shí)間去了解整個(gè)程序的運(yùn)作機(jī)制，而倘若有注釋的話，這可能只需要 5 分鐘的時(shí)間。

為了避免引入 bug，我需要理解任何小的調(diào)整可能帶來的結(jié)果。而沒有注釋，使得我必須花很長(zhǎng)時(shí)間了解每條代碼的含義和作用。尤其對(duì)于上千行的代碼來說，首先讀懂它就很耗時(shí)，想要改掉其中的某行，我必須了解小的調(diào)整可能對(duì)整體架構(gòu)和前后邏輯造成的影響。最終，在超過一個(gè)星期的時(shí)間里我只改了 180 行代碼，而這對(duì)一個(gè)動(dòng)輒千行的程序來說，改變算是很小的了。

Debug 只是寫代碼一個(gè)小的組成部分。這數(shù)千行的代碼很多我 10 年前寫的，盡管我對(duì)它們?nèi)杂行┰S殘存的記憶，但如果有注釋的話，修改代碼的過程會(huì)更加順暢，我不僅能在最短的時(shí)間里讀懂整個(gè)框架，還可以準(zhǔn)確定位我所要修改的部分。

改別人的代碼就更加困難了，每個(gè)人的思維方式都不一樣，如果沒有注釋，我通常要花費(fèi)兩倍以上的時(shí)間，只是為了修改一些細(xì)小的錯(cuò)誤。

那么，我所謂的“注釋”又是指什么呢？“注釋”是指附在代碼之后的，一段形式化規(guī)范說明的文字。但需要區(qū)分開的是，如果只是去打造一個(gè)工具室，我們是不需要一整套摩天大樓藍(lán)圖的，同樣，對(duì)于小的算法來說，我們也不需要給每條代碼加上注解。

我最近要編寫的程序，最多稱得上是“平房”，而非摩天大樓。我會(huì)為我的每個(gè)算法附上注釋，有些非常簡(jiǎn)單的算法，我通常只會(huì)插上一兩句注解。我有一個(gè)非常簡(jiǎn)單的法則來幫助我和其他人了解我的程序：注釋應(yīng)該盡可能有效地去幫助任何一個(gè)人理解和使用我的代碼。

一旦我知道一行特定代碼要做的事情后，寫的過程其實(shí)是非常簡(jiǎn)單而直接的。也有些程序需要用到非常規(guī)算法，這時(shí)我會(huì)寫下我算法的主要思路，來試探其可行性，同時(shí)也幫助我更高效的 Debug。

除了那些特別重要的代碼，通常我的注釋都是非正式的。在過去的十年里，需要我寫準(zhǔn)確并正式注釋的次數(shù)并不多。但對(duì)于一個(gè)非常復(fù)雜的系統(tǒng)來說，注釋的重要性不言自明。很少有工程師會(huì)在構(gòu)建一個(gè)復(fù)雜系統(tǒng)時(shí)，花時(shí)間去寫好注釋。有些學(xué)校也會(huì)教你怎么寫注釋，但更多時(shí)候都是教你如何寫好代碼。這需要實(shí)踐，如果你沒有畫過搭建一座平房的圖紙，你很難直接畫出摩天大樓的藍(lán)圖。

寫好注釋也沒有一個(gè)簡(jiǎn)單的準(zhǔn)則，但有一點(diǎn)你要盡量避免，那就是用代碼去解釋代碼。就好像你不能用兩個(gè)人們都不理解的東西，用其中一個(gè)去解釋另外一個(gè)。建筑師也不能直接用磚塊來告訴你，他想搭建一個(gè)什么樣的房子。

了解一個(gè)復(fù)雜的系統(tǒng)，***的辦法就是將其核心用簡(jiǎn)單的概念，抽象的概括出來。初中數(shù)學(xué)的一些基本概念可以用來幫助你寫好注釋，比如你可以用一些集合、方程和簡(jiǎn)單的邏輯來解釋你的代碼。對(duì)于一些復(fù)雜的算法，你也可以引入數(shù)學(xué)里沒有過的概念來加以解釋?？偟膩碚f，如果你的注釋偏離一些抽象的數(shù)學(xué)基本概念越遠(yuǎn)，理解起來也就越困難。

思考并不能保證我們不犯錯(cuò)，但不思考，犯錯(cuò)是無法避免的。 注釋能幫助我們將錯(cuò)誤最小化，同時(shí)它還能提高我們改錯(cuò)的效率，節(jié)省我們的時(shí)間。

英文原文：Wried

譯文鏈接：http://www.36kr.com/p/201033.html