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

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

但是很少有程序員在編碼之前，會勾畫哪怕是簡單的草圖來說明他們的程序將是會怎么樣子。

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

藍圖讓我們想清楚我們打算要建造的建筑。在寫下一段代碼之前，我們應該先寫藍圖。軟件的藍圖稱為技術說明書。

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

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

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

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

修改代碼只是一項大任務中小小的一塊工作，大多數代碼已經是我十幾年之前寫的了。盡管我幾乎不記得這些代碼是干嘛的，要修改它還是挺容易的——通過閱讀我寫的技術說明書，很容易就能找到我要修改的地方。盡管這些修改工作量不少，而且還影響到其它代碼，我還是能很快搞定它。

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

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

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

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

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

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

理解一件復雜的事情的關鍵是抽象，這意味著技術說明比代碼要高一個層次。最簡單最準確的語言是數學，初等數學就教過這些了：集合、函數和簡單的邏輯。不過，大多數正式的技術說明書使用的語言不在初等數學班里，比如：類型。然而，越是遠離簡單數學的語言，越會妨礙我們去理解一個復雜的程序或系統。

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

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

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