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

同樣，如果說(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)始寫(xiě)代碼之前，連一個(gè)粗略的框架都沒(méi)有。

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

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

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

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

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

這種想法是錯(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)有注釋?zhuān)沟梦冶仨毣ê荛L(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 只是寫(xiě)代碼一個(gè)小的組成部分。這數(shù)千行的代碼很多我 10 年前寫(xiě)的，盡管我對(duì)它們?nèi)杂行┰S殘存的記憶，但如果有注釋的話，修改代碼的過(guò)程會(huì)更加順暢，我不僅能在最短的時(shí)間里讀懂整個(gè)框架，還可以準(zhǔn)確定位我所要修改的部分。

改別人的代碼就更加困難了，每個(gè)人的思維方式都不一樣，如果沒(méi)有注釋?zhuān)彝ǔＲㄙM(fèi)兩倍以上的時(shí)間，只是為了修改一些細(xì)小的錯(cuò)誤。

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

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

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

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

寫(xiě)好注釋也沒(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)幫助你寫(xiě)好注釋?zhuān)热缒憧梢杂靡恍┘?、方程和?jiǎn)單的邏輯來(lái)解釋你的代碼。對(duì)于一些復(fù)雜的算法，你也可以引入數(shù)學(xué)里沒(méi)有過(guò)的概念來(lái)加以解釋。總的來(lái)說(shuō)，如果你的注釋偏離一些抽象的數(shù)學(xué)基本概念越遠(yuǎn)，理解起來(lái)也就越困難。

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

英文原文：Wried

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