代码中的注释

我第一个实习的公司,是一个美资公司,在印度设立研发中心可能都已经有超过10年的经验了,那时候一些前辈们告诉我,印度人写的代码可能不如中国人那么聪明,但是他们的注释实在是非常详细,有时候甚至达到了1:1的比例,试想想,100行代码就有100行注释,这是多么的恐怖啊。

经常听到会有人抱怨道,怎么这段代码没有注释啊,这是为什么这样写的啊,如此云云。仿佛没有注释,这个世界就不转了。类似的事情也经常发生在QA们的身边,只不过注释换成了文档。

刚毕业的时候做白盒测试,现在回想起来,那时候的我测试的代码大部分都是不包含注释的,不过我测试起来并没有太大的困难,总结一下,应该有以下几点原因:

  1. 有意义的函数名、变量名。函数的命名让人一看就大概知道在做什么,例如PostBlog就是发布一篇博客,如果遇到一个叫SaveProfile的方法但做的却是加好友,那我想再多的注释我也会头晕
  2. 代码不会说谎。根据经验,如果一段代码理解起来很费劲,那么通常里面都会隐藏着问题。代码就是最好的注释,一些过时的注释,设置会对阅读代码的人产生误导
  3. 充分的沟通。虽然游走于几个项目组,跟不同的开发人员打交道,但是每当遇到问题的时候总会主动跟相关的人沟通,一个活生生的人坐在那里不问,却迷信什么文档,这真是本末倒置

注释,能不写就别写,实在要写,写WHY而不是WHAT。

联系一下最近在Team内写的一个新的回归测试工具,里面基本没有注释,希望过几个月以后,自己还能够看看代码就知道当时那段代码为什么这样写。

4 thoughts on “代码中的注释”

  1. 没有人愿意写文档,尤其是agile开发里变化这么快文档更新估计跟不上代码。这里我就觉得注释很重要,而且有时候连developer自己都想不起做了什么为什么这样做,所以我一般都不问developer。

    不过自己做的是integrated test以上的level的,其实大部分时间不会去看代码要做什么,如果那样的话就会放过很多bug。就像James Bach说的,不相信developer,也不相信他们的code

  2. linuxcity,我很同意你的观点,敏捷开发里面的确没有人愿意写文档,因为代码更新的快,文档如果不能随着代码一起更新,那只能贻害后人。
    不相信developer,也不相信他们的code — 经典 :)

  3. 我现在觉得测试之前如果不写个具体的文档,或者说写个测试计划,那么会隐藏许多问题和漏洞,在写文档和计划的过程中可以发现很多的问题及时补上,让测试变得更准确

Leave a Reply

Your email address will not be published. Required fields are marked *