像建筑设计师一样去写代码
同样，如果说建筑师最后的成品是建筑的话，那么程序员和软件工程师最终的成品就是软件。在实际动工之前，建筑师将会将建筑的每一个细节，都在蓝图上加以呈现。只是程序员和软件工程师并不会这么做。或许，这就是为什么房子很少倒塌，而软件却经常崩溃的原因？
设计蓝图会帮助建筑师确定他们的设计是可行的。“可行”并非只是保证不倒塌，它同时还意味着，建筑能够达到预定的服务于人的目标。客户或者开发商，也是通过蓝图去了解一个设计师的想法和他正打算去做的事情。
相较之下，很多程序员在他们开始写代码之前，连一个粗略的框架都没有。
大部分的程序员都认为：所有不能直接产出代码的事情都是没有意义的。思考并不能直接转换成代码，但是倘若在没有一个整体框架之前，就开始匆忙码字，这也是没有意义的。在程序员开始写代码之前，他们应该先充分理解这些代码最终所要实现的功能。理解的过程，自然需要去思考，而将思考过程写下来，对于程序员来说又是件很耗时的事儿。
但漫画家 Dick Guindon 曾经所过： 写作是发现你想法有多糟糕的最好的方式。
蓝图帮助我们理解建筑的构架，同样，在我们开始噼里啪啦写代码之前，我们也需要一个类似的“蓝图”，也就是“注释”(specification)。
“注释”不能直接产出代码，所以被很多程序员忽视。但没有“注释”，直接开写，就好像让建筑承包商没有设计师的图纸就直接上阵一样。
也有人会说，将程序员和建筑师类比，并不合理。因为拆墙重建困难，但删掉重写则相对容易，所以，程序员可以先写着，不满意再改。
这种想法是错的。为什么呢？因为 Debug 的过程也非常耗时。
我最近也完善了一些程序，这个过程需要对程序构架本身有个非常清晰的了解。我花了接近一天的时间去了解整个程序的运作机制，而倘若有注释的话，这可能只需要 5 分钟的时间。
为了避免引入 bug，我需要理解任何小的调整可能带来的结果。而没有注释，使得我必须花很长时间了解每条代码的含义和作用。尤其对于上千行的代码来说，首先读懂它就很耗时，想要改掉其中的某行，我必须了解小的调整可能对整体架构和前后逻辑造成的影响。最终，在超过一个星期的时间里我只改了 180 行代码，而这对一个动辄千行的程序来说，改变算是很小的了。
Debug 只是写代码一个小的组成部分。这数千行的代码很多我 10 年前写的，尽管我对它们仍有些许残存的记忆，但如果有注释的话，修改代码的过程会更加顺畅，我不仅能在最短的时间里读懂整个框架，还可以准确定位我所要修改的部分。
改别人的代码就更加困难了，每个人的思维方式都不一样，如果没有注释，我通常要花费两倍以上的时间，只是为了修改一些细小的错误。
那么，我所谓的“注释”又是指什么呢？“注释”是指附在代码之后的，一段形式化规范说明的文字。但需要区分开的是，如果只是去打造一个工具室，我们是不需要一整套摩天大楼蓝图的，同样，对于小的算法来说，我们也不需要给每条代码加上注解。
我最近要编写的程序，最多称得上是“平房”，而非摩天大楼。我会为我的每个算法附上注释，有些非常简单的算法，我通常只会插上一两句注解。我有一个非常简单的法则来帮助我和其他人了解我的程序：注释应该尽可能有效地去帮助任何一个人理解和使用我的代码。
一旦我知道一行特定代码要做的事情后，写的过程其实是非常简单而直接的。也有些程序需要用到非常规算法，这时我会写下我算法的主要思路，来试探其可行性，同时也帮助我更高效的 Debug。
除了那些特别重要的代码，通常我的注释都是非正式的。在过去的十年里，需要我写准确并正式注释的次数并不多。但对于一个非常复杂的系统来说，注释的重要性不言自明。很少有工程师会在构建一个复杂系统时，花时间去写好注释。有些学校也会教你怎么写注释，但更多时候都是教你如何写好代码。这需要实践，如果你没有画过搭建一座平房的图纸，你很难直接画出摩天大楼的蓝图。
写好注释也没有一个简单的准则，但有一点你要尽量避免，那就是用代码去解释代码。就好像你不能用两个人们都不理解的东西，用其中一个去解释另外一个。建筑师也不能直接用砖块来告诉你，他想搭建一个什么样的房子。
了解一个复杂的系统，最好的办法就是将其核心用简单的概念，抽象的概括出来。初中数学的一些基本概念可以用来帮助你写好注释，比如你可以用一些集合、方程和简单的逻辑来解释你的代码。对于一些复杂的算法，你也可以引入数学里没有过的概念来加以解释。总的来说，如果你的注释偏离一些抽象的数学基本概念越远，理解起来也就越困难。
思考并不能保证我们不犯错，但不思考，犯错是无法避免的。注释能帮助我们将错误最小化，同时它还能提高我们改错的效率，节省我们的时间。