这些日子，我写的程序往往只是小房子级别，不是摩天大楼级的。通常我会写下每个算法的实现方式，大多数算法很简单，可能只需要一两句话就能写清楚。有时写清楚一个算法到底是怎么起作用的需要好好构思，并且可能得花上一段话或者几页纸才能写清楚。我有一个简单的原则：技术说明书应该写清楚该算法的使用者需要知道的每一件事情。在代码写好、编译好之后，估计没有人会再去阅读它了。

　　一旦我弄明白了一段代码的目的所在，写代码的工作就容易了。但有些代码并不是这样，它们要求很复杂的算法。想让一个算法运作起来需要精心构思，这就需要有技术说明书了。

　　我写的大多数技术说明书都是非正式的。偶尔一段代码很精妙，也很关键，这就需要正式地写。要保证准确性，甚至要使用编写工具仔细检查。这种正式的事情过去十几年只是有那么十几次罢了。

　　对于复杂系统的设计师，一份正式的技术说明书是必须的，就好像摩天大楼的蓝图一样。但很少有工程师会撰写技术说明书，因为他们根本没有时间去学如何做好这件事，而且学校里也不教。一些学校会讲授技术说明书用语，但是很少教怎么在实际工作中应用。如果你连一个工具棚的蓝图都不会画的话，怎么能会画摩天大楼的蓝图?

　　要学会撰写技术说明书，需要实践。没有简单的规则能保证你写出一份好的技术说明书。不过一个应该避免的事情就是不要用代码。通过代码去理解代码是一个糟糕事情。建筑设计师不会用砖来制作蓝图。

　　理解一件复杂的事情的关键是抽象，这意味着技术说明比代码要高一个层次。最简单最准确的语言是数学，初等数学就教过这些了：集合、函数和简单的逻辑。不过，大多数正式的技术说明书使用的语言不在初等数学班里，比如：类型。然而，越是远离简单数学的语言，越会妨碍我们去理解一个复杂的程序或系统。

　　无论是为复杂系统使用正式的技术说明书还是简单代码的非正式的技术说明书，撰写技术说明书都会提升我们代码的质量。它有助于我们理解我们正在做的事情并减少出错。当然，即使撰写技术说明书也不保证你的程序就不会崩溃。我们依然要使用已有的其它方法和工具来减少代码缺陷。

　　思考不会保证我们不会犯错误。但是不思考肯定会犯错误。

　　本文作者莱斯利.兰伯特是计算机科学家，擅长分布式系统、时态逻辑和并行算法。他是工程和国家科学院国家科学院成员。兰伯特在麻省理工学院攻读数学本科，在布兰迪斯大学赢得了他的硕士和博士学位。他为微软研究所工作。