像建筑设计师一样去写程序

6顶
3踩

2013-01-28 17:39 by 副主编 WnouM 评论(13) 有5948人浏览

开发代码注释

写代码和写文章，从某种程度上是相通的，需要逻辑、构架，也要尽可能的简练。我们之前说过，创作者的时间表和管理者的时间表是不一样的，编代码和写文章，都是一个孤独而不能受到干扰的过程，面对屏幕，就是一场自己与自己的战争。

同样，如果说建筑师最后的成品是建筑的话，那么程序员和软件工程师最终的成品就是软件。在实际动工之前，建筑师将会将建筑的每一个细节，都在蓝图上加以呈现。只是程序员和软件工程师并不会这么做。或许，这就是为什么房子很少倒塌，而软件却经常崩溃的原因？

设计蓝图会帮助建筑师确定他们的设计是可行的。“可行”并非只是保证不倒塌，它同时还意味着，建筑能够达到预定的服务于人的目标。客户或者开发商，也是通过蓝图去了解一个设计师的想法和他正打算去做的事情。

相较之下，很多程序员在他们开始写代码之前，连一个粗略的框架都没有。

大部分的程序员都认为：所有不能直接产出代码的事情都是没有意义的。思考并不能直接转换成代码，但是倘若在没有一个整体框架之前，就开始匆忙码字，这也是没有意义的。在程序员开始写代码之前，他们应该先充分理解这些代码最终所要实现的功能。理解的过程，自然需要去思考，而将思考过程写下来，对于程序员来说又是件很耗时的事儿。

但漫画家 Dick Guindon 曾经所过：

引用

写作是发现你想法有多糟糕的最好的方式。

蓝图帮助我们理解建筑的构架，同样，在我们开始噼里啪啦写代码之前，我们也需要一个类似的“蓝图”，也就是“注释”(specification)。

“注释”不能直接产出代码，所以被很多程序员忽视。但没有“注释”，直接开写，就好像让建筑承包商没有设计师的图纸就直接上阵一样。

也有人会说，将程序员和建筑师类比，并不合理。因为拆墙重建困难，但删掉重写则相对容易，所以，程序员可以先写着，不满意再改。

这种想法是错的。为什么呢？因为 Debug 的过程也非常耗时。

我最近也完善了一些程序，这个过程需要对程序构架本身有个非常清晰的了解。我花了接近一天的时间去了解整个程序的运作机制，而倘若有注释的话，这可能只需要 5 分钟的时间。

为了避免引入 bug，我需要理解任何小的调整可能带来的结果。而没有注释，使得我必须花很长时间了解每条代码的含义和作用。尤其对于上千行的代码来说，首先读懂它就很耗时，想要改掉其中的某行，我必须了解小的调整可能对整体架构和前后逻辑造成的影响。最终，在超过一个星期的时间里我只改了 180 行代码，而这对一个动辄千行的程序来说，改变算是很小的了。

Debug 只是写代码一个小的组成部分。这数千行的代码很多我 10 年前写的，尽管我对它们仍有些许残存的记忆，但如果有注释的话，修改代码的过程会更加顺畅，我不仅能在最短的时间里读懂整个框架，还可以准确定位我所要修改的部分。

改别人的代码就更加困难了，每个人的思维方式都不一样，如果没有注释，我通常要花费两倍以上的时间，只是为了修改一些细小的错误。

那么，我所谓的“注释”又是指什么呢？“注释”是指附在代码之后的，一段形式化规范说明的文字。但需要区分开的是，如果只是去打造一个工具室，我们是不需要一整套摩天大楼蓝图的，同样，对于小的算法来说，我们也不需要给每条代码加上注解。

我最近要编写的程序，最多称得上是“平房”，而非摩天大楼。我会为我的每个算法附上注释，有些非常简单的算法，我通常只会插上一两句注解。我有一个非常简单的法则来帮助我和其他人了解我的程序：注释应该尽可能有效地去帮助任何一个人理解和使用我的代码。

一旦我知道一行特定代码要做的事情后，写的过程其实是非常简单而直接的。也有些程序需要用到非常规算法，这时我会写下我算法的主要思路，来试探其可行性，同时也帮助我更高效的 Debug。

除了那些特别重要的代码，通常我的注释都是非正式的。在过去的十年里，需要我写准确并正式注释的次数并不多。但对于一个非常复杂的系统来说，注释的重要性不言自明。很少有工程师会在构建一个复杂系统时，花时间去写好注释。有些学校也会教你怎么写注释，但更多时候都是教你如何写好代码。这需要实践，如果你没有画过搭建一座平房的图纸，你很难直接画出摩天大楼的蓝图。

写好注释也没有一个简单的准则，但有一点你要尽量避免，那就是用代码去解释代码。就好像你不能用两个人们都不理解的东西，用其中一个去解释另外一个。建筑师也不能直接用砖块来告诉你，他想搭建一个什么样的房子。

了解一个复杂的系统，最好的办法就是将其核心用简单的概念，抽象的概括出来。初中数学的一些基本概念可以用来帮助你写好注释，比如你可以用一些集合、方程和简单的逻辑来解释你的代码。对于一些复杂的算法，你也可以引入数学里没有过的概念来加以解释。总的来说，如果你的注释偏离一些抽象的数学基本概念越远，理解起来也就越困难。

思考并不能保证我们不犯错，但不思考，犯错是无法避免的。注释能帮助我们将错误最小化，同时它还能提高我们改错的效率，节省我们的时间。

Via Wried

来自: 36氪

分享到：

6
顶

3
踩

评论共 13 条请登录后发表评论

13 楼 likitty 2014-09-04 20:36

这篇文章的标题非常吸引人，内容主旨也是正确的，要写好注释

12 楼 thoughtbear 2013-01-31 15:17

    首先感谢作者，因为我本人就是一个很少写注释的人，你的文章让我重新认真思考了这个问题。
    我个人很少写注释的原因：
    1.代码免不了被修改，有时候是直接修改，有时候是通过IED的rename之类的快捷方式间接修改，修改了代码后必须保证注释也随之更新，否则，时间长了，注释也许就成误导了。
    2.个人一直坚持认为：注释是下策，如果程序写的足够清晰，命名足够明了，阅读者一看就能懂，也就不需要注释了。实在没办法的时候才写注释。
    你的文章引起了我的再思考，但实际情况中，1其实是可以通过细心基本解决的，2则有些理想化，不见得总有时间让代码本身足够明晰。
    我觉得这是篇优质文章，虽不完美。顶一个！

11 楼 zhentiwei 2013-01-31 12:37

我觉得 specification 是规格吧？
编码之前需要规格这个容易理解，如果是注射，感觉怪怪的。

10 楼 jianshuai 2013-01-31 09:52

通篇就是一个意思：写代码要思考，要写注释。。毛啊，这么长一点，这么思考。。什么样在的注释都木有说。。。

9 楼敲代码的小北 2013-01-30 15:42

2楼亮了。。

8 楼 yusimiao 2013-01-29 19:56

有相通之处就值得学习，取其精华去其糟粕！

7 楼 Julien 2013-01-29 14:16

企图把软件行业混同于传统行业，是行业里最幼稚低级而且心怀不轨的胡说八道了。
建筑业会随时把盖好的楼层拆掉换成完全不同的层么？
任何制造业面临的设计上/架构上的挑战，跟软件业比起来都是小儿科。

6 楼 leric 2013-01-29 09:56

specification是注释？comments是啥？

5 楼 wangguo 2013-01-29 09:34

edhn 写道

挑个语病吧，“很少有程序员会在他们开始写代码之前，连一个粗略的框架都没有。 ”这句话的意思是很多程序员至少有一个粗略的框架

已改，“相较之下，很多程序员在他们开始写代码之前，连一个粗略的框架都没有。”

4 楼 LucasLee 2013-01-28 21:21

这个类比只能粗略的比，细化一点你会发现根本没法比。
“或许，这就是为什么房子很少倒塌，而软件却经常崩溃的原因？ ”
房子如果只要保证不塌，那可能还是相对简单的吧。软件如果只要不崩溃，只怕也是比较简单的，比如用java ：）

软件的复杂性比建筑明显大的一个方面，就是持续可变，一个房子建好之后，基本不太变动了吧，但是软件变动明显比它大得多。

3 楼 zhongmin2012 2013-01-28 19:45

freezingsky 写道

在我看来，凡是工程类的学科，很多内容都是相通。

哈哈，精炼

2 楼 edhn 2013-01-28 19:05

挑个语病吧，“很少有程序员会在他们开始写代码之前，连一个粗略的框架都没有。 ”这句话的意思是很多程序员至少有一个粗略的框架

1 楼 freezingsky 2013-01-28 18:29

在我看来，凡是工程类的学科，很多内容都是相通。

发表评论

您还没有登录,请您登录后再发表评论

6顶3踩