• 2010-01-05

    当注释遇到版本控制

    版权声明:转载时请以超链接形式标明文章原始出处和作者信息及本声明
    http://www.blogbus.com/dreamhead-logs/56226747.html

    如果你编程有些日子了,下面这样的注释,你应该不会陌生:
    /*
     * 2010-01-03: Added amazing functionality
     * 2010-01-04: Modified amazing functionality
     * 2010-01-05: Deleted amazing functionality
     */

    这个注释在干什么?没错,它是代码的日志,说明了这段代码一路走来的历史。有了这样的注释,我们不费吹灰之力就可以了解到远古时代发生了什么,所以,这样的注释价值很大。确实,在远古时代,这样的注释价值很大。但后来,随着时代进步,有一类叫做版本控制的软件出现了。

    版本控制软件最基本的一个用法就是在提交代码时加上注释:
        svn ci -m"the reason I submit code"

    接下来,我们可以找到每个变化的原因
        svn log foo.c

    除了这种日志式代码,还有很多人愿意在代码里签名:
    /* Added by dreamhead */

    不错,好汉做事好汉当。但是,在这个版本控制发达的年代,你以为不签名就跑得了吗?
        svn blame foo.c

    这样签名式注释本意是要告诉别人,应该和谁讨论这段代码。但那些年代久远的代码是不断发展的,由于很多人做好事不留名,这段代码和留名的人关系越来越小。况且,在这个跳槽犹如家常便饭的年代,留名的那位可能早就不知影踪了。

    为了给后来者留下回旋余地,还有些好心人只是把一些有意删除的代码注释掉。
    // var = 1;

    请放心,送这样的代码到该去的地方。需要的话,我们可以把它找回来:
        svn diff -r1:100 foo.c

    好吧!你知道我要说什么了。在这个源码控制已经像牙膏、香皂一样成为生活日用品的年代,别在像只远古恐龙一样替版本控制工具写那些无用的注释了。动手删除吧!

    什么?你不用版本控制?I服了You!

    参考资料
    Clean Code》(中文版《代码整洁之道》)

    分享到:

    历史上的今天:

    扩大防守 2009-01-05
    引用地址:

    评论

  • 很多时候在文件里 修改缺陷的时候会加上
    //modify for issue XX(or some document)
    虽然已经有版本控制了 但是代码里面有简短说明的话,后面的修复人员一看就能很明显的知道,为了什么加上这段代码 .
    svn 有的时候并不好用(麻烦一点)。因为一个很长的文件 如果你想知道这一段为什么这样写,就只能翻阅到三个月到之前的修改人员加的注释...
  • 是啊,现实就是有人还固执的生活在远古时代,并且弄得现代人好像是异类。
  • 和博主请教一个问题

    在执行svn log后,会出现如下信息

    r 100 | 作者 | 日期
    一些信息


    请问这里的“作者”该怎么设置呢,类似于git里面的git config --global user.name 'your name',这个问题找了很久也没有找到(使用SVN我属于半路出家那种,也许这个问题很弱,呵呵,望赐教)
    回复星情说:
    google "svn 修改用户"
    2010-01-25 08:36:52