在砌上一塊磚或釘下一支釘子之前，建筑設(shè)計師會制定好詳細(xì)的計劃。程序員或者軟件工程師卻不會。這難道就是房子很少塌倒而程序經(jīng)常會崩潰的原因？

藍(lán)圖保證建筑設(shè)計師的設(shè)計的建筑按規(guī)劃建成。“建成”不僅僅意味不會塌倒，還意味達(dá)到業(yè)主要求的功能。建筑設(shè)計師和他們的客戶在著手建造之前，通過藍(lán)圖來溝通，以理解他們將要建造成的建筑的樣子。

但是很少有程序員在編碼之前，會勾畫哪怕是簡單的草圖來說明他們的程序?qū)⑹菚趺礃幼印?/p>

大多數(shù)程序員認(rèn)為做任何不產(chǎn)生代碼的事情都是浪費時間。思考并不會產(chǎn)生代碼，沒有想好就開始編碼，那只會產(chǎn)生出糟糕代碼。我們應(yīng)該理解這些代碼到底要實現(xiàn)哪些功能。理解需要思考，而思考很難。借用一句漫畫家迪克·圭尼登的話：

藍(lán)圖讓我們想清楚我們打算要建造的建筑。在寫下一段代碼之前，我們應(yīng)該先寫藍(lán)圖。軟件的藍(lán)圖稱為技術(shù)說明書。

已經(jīng)有太多的借口說撰寫技術(shù)說明書只是浪費時間。比如：技術(shù)說明書毫無用處，我們不能通過它來產(chǎn)生代碼。這就好像說建筑設(shè)計師應(yīng)該不要畫藍(lán)圖，因為他們最終還是需要承包商去建造房子。另外一個反對撰寫技術(shù)說明書的爭論也能夠用藍(lán)圖的例子來反駁。

還有一些程序員爭辯說，把藍(lán)圖和技術(shù)說明書作比較是無用功，畢竟程序不是建筑物。他們認(rèn)為推倒一堵墻要比改變代碼難多了，所以程序的藍(lán)圖不是必須的。

錯！改變代碼也很難，特別是如果我們不想讓程序有缺陷的話。

我最近需要修改一些不是我寫的代碼，從而給程序增加一個小小的功能。要完成它需要理解一個接口。我花一整天用調(diào)試器來研究該接口到底是干什么的——這種事讀讀技術(shù)說明書只要5分鐘就能搞定。為了避免導(dǎo)入缺陷，我不得不弄清楚我每次修改之后的結(jié)果。因為沒有技術(shù)說明書，這個事情變得更加困難。我必須要閱讀上千行代碼，我花了數(shù)天來琢磨怎樣才能修改盡可能少的代碼。最后，我花了一周，新增、修改了180行代碼。這可僅僅是這個程序的一個很小的變更啊。

修改代碼只是一項大任務(wù)中小小的一塊工作，大多數(shù)代碼已經(jīng)是我十幾年之前寫的了。盡管我?guī)缀醪挥浀眠@些代碼是干嘛的，要修改它還是挺容易的——通過閱讀我寫的技術(shù)說明書，很容易就能找到我要修改的地方。盡管這些修改工作量不少，而且還影響到其它代碼，我還是能很快搞定它。

我所說的技術(shù)說明書到底是什么？通常它被認(rèn)為是以正式的技術(shù)語言寫就的東西。但是撰寫正式的技術(shù)說明只需要偶爾為之，如果我們僅僅是蓋個工具棚的話，就不需要畫摩天大樓所要求的那種藍(lán)圖。對于大多數(shù)軟件來說，我們不需要正式的技術(shù)說明書。然而就算是寫小程序也不能不寫技術(shù)說明，否則就像沒做任何計劃就要蓋工具棚一樣。

這些日子，我寫的程序往往只是小房子級別，不是摩天大樓級的。通常我會寫下每個算法的實現(xiàn)方式，大多數(shù)算法很簡單，可能只需要一兩句話就能寫清楚。有時寫清楚一個算法到底是怎么起作用的需要好好構(gòu)思，并且可能得花上一段話或者幾頁紙才能寫清楚。我有一個簡單的原則：技術(shù)說明書應(yīng)該寫清楚該算法的使用者需要知道的每一件事情。在代碼寫好、編譯好之后，估計沒有人會再去閱讀它了。

一旦我弄明白了一段代碼的目的所在，寫代碼的工作就容易了。但有些代碼并不是這樣，它們要求很復(fù)雜的算法。想讓一個算法運作起來需要精心構(gòu)思，這就需要有技術(shù)說明書了。

我寫的大多數(shù)技術(shù)說明書都是非正式的。偶爾一段代碼很精妙，也很關(guān)鍵，這就需要正式地寫。要保證準(zhǔn)確性，甚至要使用編寫工具仔細(xì)檢查。這種正式的事情過去十幾年只是有那么十幾次罷了。

對于復(fù)雜系統(tǒng)的設(shè)計師，一份正式的技術(shù)說明書是必須的，就好像摩天大樓的藍(lán)圖一樣。但很少有工程師會撰寫技術(shù)說明書，因為他們根本沒有時間去學(xué)如何做好這件事，而且學(xué)校里也不教。一些學(xué)校會講授技術(shù)說明書用語，但是很少教怎么在實際工作中應(yīng)用。如果你連一個工具棚的藍(lán)圖都不會畫的話，怎么能會畫摩天大樓的藍(lán)圖？

要學(xué)會撰寫技術(shù)說明書，需要實踐。沒有簡單的規(guī)則能保證你寫出一份好的技術(shù)說明書。不過一個應(yīng)該避免的事情就是不要用代碼。通過代碼去理解代碼是一個糟糕事情。建筑設(shè)計師不會用磚來制作藍(lán)圖。

理解一件復(fù)雜的事情的關(guān)鍵是抽象，這意味著技術(shù)說明比代碼要高一個層次。最簡單最準(zhǔn)確的語言是數(shù)學(xué)，初等數(shù)學(xué)就教過這些了：集合、函數(shù)和簡單的邏輯。不過，大多數(shù)正式的技術(shù)說明書使用的語言不在初等數(shù)學(xué)班里，比如：類型。然而，越是遠(yuǎn)離簡單數(shù)學(xué)的語言，越會妨礙我們?nèi)ダ斫庖粋€復(fù)雜的程序或系統(tǒng)。

無論是為復(fù)雜系統(tǒng)使用正式的技術(shù)說明書還是簡單代碼的非正式的技術(shù)說明書，撰寫技術(shù)說明書都會提升我們代碼的質(zhì)量。它有助于我們理解我們正在做的事情并減少出錯。當(dāng)然，即使撰寫技術(shù)說明書也不保證你的程序就不會崩潰。我們依然要使用已有的其它方法和工具來減少代碼缺陷。

思考不會保證我們不會犯錯誤。但是不思考肯定會犯錯誤。

本文作者萊斯利.蘭伯特是計算機(jī)科學(xué)家，擅長分布式系統(tǒng)、時態(tài)邏輯和并行算法。他是工程和國家科學(xué)院國家科學(xué)院成員。蘭伯特在麻省理工學(xué)院攻讀數(shù)學(xué)本科，在布蘭迪斯大學(xué)贏得了他的碩士和博士學(xué)位。他為微軟研究所工作。