V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
gangsta
V2EX  ›  程序员

发现同事们很喜欢写这样的代码注释...

  •  
  •   gangsta · 2014-04-03 10:11:35 +08:00 · 9955 次点击
    这是一个创建于 3888 天前的主题,其中的信息可能已经有所发展或是发生改变。
    //************* xxx function START *************//

    code block...

    //************* xxx function END *************//

    还有一个是维护类代码的注释,在我待过的公司,以及被外派,出差,各种onsite/offshore合作过的公司中,同样发现很多人都喜欢这么写...

    先把bug代码块注释掉,然后...

    //************* modified by xxx at 2013-02-14 for xxx reason START *************//

    code block...

    //************* modified by xxx at 2013-02-14 for xxx reason END *************//
    53 条回复    1970-01-01 08:00:00 +08:00
    zoowii
        1
    zoowii  
       2014-04-03 10:19:39 +08:00
    我先注释,跑通没问题的话第二天就删掉
    ivenvd
        2
    ivenvd  
       2014-04-03 10:21:36 +08:00
    不会用版本管理的同事……
    muzuiget
        3
    muzuiget  
       2014-04-03 10:32:50 +08:00
    我也很烦这种到处留名的注释,大块无用代码注释,靠,用版本管理的话,什么都清清楚楚了。
    lyragosa
        4
    lyragosa  
       2014-04-03 10:36:00 +08:00
    我也很喜欢用这种注释
    nicai000
        5
    nicai000  
       2014-04-03 10:49:28 +08:00
    xxx blame多好用的
    bengol
        6
    bengol  
       2014-04-03 10:53:07 +08:00   ❤️ 1
    比用中文注释好多了,各种编码切换~
    wvidc
        7
    wvidc  
       2014-04-03 11:17:14 +08:00
    很好啊 方便二次开发 容易上手
    wizardoz
        8
    wizardoz  
       2014-04-03 11:28:37 +08:00
    还有一种,要在函数注释头中写上调用了哪些函数,以及被哪些函数调用。各种蛋疼。
    likai
        9
    likai  
       2014-04-03 11:30:41 +08:00
    我怎么觉得不错,别人接手一看明
    lu18887
        10
    lu18887  
       2014-04-03 11:31:59 +08:00
    在LINUX 下VI编程,这种注释已经是很友好的了!版本控制工具,在图形化界面下很nice,但是在命令行下就没那么明了了。
    lemonlwz
        11
    lemonlwz  
       2014-04-03 11:34:37 +08:00
    如何一行注释都没有,会否习惯呢?
    wlh
        12
    wlh  
       2014-04-03 11:59:51 +08:00
    我自己的Blog代码都这么写……下次一看就知道,否则经常忘了这块是什么用的要想半天
    Pixeller
        13
    Pixeller  
       2014-04-03 12:04:45 +08:00
    挺好的, lz你哪天看到一大段一大段被别人改, 如果别人没有注释, 谁知道哪里被框掉了? 小改动看看blame还行, 日积月累, 还能看得过来?
    FrankFang128
        14
    FrankFang128  
       2014-04-03 12:09:25 +08:00
    WebStorm 自动添加 function separator,这个功能还是有点用的
    DogonLin
        15
    DogonLin  
       2014-04-03 12:10:59 +08:00
    做SAP的时候里面基本都是这种注释。。。。
    NetCobra
        16
    NetCobra  
       2014-04-03 12:18:27 +08:00
    我不喜欢这种注释,这种活应该是版本管理的功能,不应该用注释来干。
    raincious
        17
    raincious  
       2014-04-03 12:21:03 +08:00
    @lu18887 我一直以为git branch new_branch和git add new_file.c是在命令行下敲的。
    bsbgong
        18
    bsbgong  
       2014-04-03 12:40:21 +08:00
    1. 这注释很好,我也喜欢这样写的,不过现在的team guidelines里不许这样写了。看各团队自己的规范,大家一致遵守就好。
    2. 程序注释就没必要吐槽了。个人趣味不同,你觉得不好用的别人觉得好用。
    wdlth
        19
    wdlth  
       2014-04-03 12:45:54 +08:00
    我一般用DOC型注释
    /**
    * 描述
    *
    * @author 作者
    * @version 版本
    * @package
    *
    */
    这类的
    wklken
        20
    wklken  
       2014-04-03 13:05:27 +08:00
    刚毕业那会在的公司很喜欢用,因为代码管理混乱,特别是一些不得不改的公用部分
    声明的目的是界定说这块代码是xxx加的,没事别乱改,要改去找当事人

    不过好久没见到了......
    slixurd
        21
    slixurd  
       2014-04-03 13:14:42 +08:00
    xxx modify没啥必要,但是修改原因还是很有意义的
    函数顶部外加doc型注释,说清楚参数含义,调用方式
    我是没见过几个人看源代码开着git blame来看的,又没高亮又不方便跳转
    用来差错定位是谁改错用git blame还差不多
    viator42
        22
    viator42  
       2014-04-03 13:16:46 +08:00
    这种注释方式很好用.
    尤其是在行数很多的文件里分隔不同的功能模块,看起来一目了然.
    做版本管理的话太原始了.
    以前还有必须是80个字符的规定.
    ichou
        23
    ichou  
       2014-04-03 13:25:18 +08:00
    html 和 css 里面才用这种 start end 的注释
    其他的都严格按照 DOC 来写
    我会说我曾经在自己写的类注释里面还画了一个 逻辑流程图示 么?小伙伴看到那个注释可带劲儿了
    parthenon2007
        24
    parthenon2007  
       2014-04-03 13:29:44 +08:00
    知足吧,这已经很好了,至少还可以看出来以前是因为什么原因修改了代码。何况有时也无法连接到版控。
    emanonwzy
        25
    emanonwzy  
       2014-04-03 13:38:53 +08:00
    我待的第一家公司也是这样,据说是为了出bug可以找到修改的人。。。
    xiaowangge
        26
    xiaowangge  
       2014-04-03 14:07:18 +08:00 via Android
    昨天刚接触到的: package-info.java

    ,-)
    loading
        27
    loading  
       2014-04-03 14:40:45 +08:00 via iPhone
    html喜欢用start和end
    lu18887
        28
    lu18887  
       2014-04-03 15:30:17 +08:00
    @raincious 看公司把,互联网公司用GIT的可能性大一些,传统的都还是SVN。
    tonic
        29
    tonic  
       2014-04-03 15:33:40 +08:00
    @lu18887 svn不也是命令敲么... svn co, svn ci -m, svn sw --force, svn merge...
    lu18887
        30
    lu18887  
       2014-04-03 15:36:06 +08:00
    @tonic 但我从来没用命令行的svn看过log ……
    raincious
        31
    raincious  
       2014-04-03 15:59:29 +08:00
    @lu18887

    其实是历史原因哈。不过另外SVN有一个巨大的好处,就是你想要commit,必须commit到服务器上,这样大家都能看到,不会有本地堆积了一堆commit之后,push时的冲突。
    caizeng
        32
    caizeng  
       2014-04-03 16:35:08 +08:00
    我觉得这是一个好习惯
    janxin
        33
    janxin  
       2014-04-03 17:00:00 +08:00
    以前学VC和VB的时候,挺常见的...
    Livid
        34
    Livid  
    MOD
       2014-04-03 17:02:27 +08:00   ❤️ 1
    最好不要在线上的代码里留注释掉的代码。这个东西就是读代码的人的精神负担和改代码的人的定时炸弹。

    这些代码应该加一个容易搜索的关键字留在版本控制历史里。
    hkongm
        35
    hkongm  
       2014-04-03 17:17:57 +08:00
    多好的习惯啊。
    如果没有版本管理这样是最好的了。
    还有上面有的同学说版本管理,有几个人认真填写commit comment的?我认识的,除了我一个人,没人认真写。。。
    tonic
        36
    tonic  
       2014-04-03 17:40:59 +08:00
    @lu18887 不过也是... 因为太难看了= =#
    lightening
        37
    lightening  
       2014-04-03 17:44:53 +08:00   ❤️ 1
    我们公司的代码规范说无特殊情况禁止写注释…… 如果你的代码要注释才能看懂,说明代码写坏了,回去重构。另外说明性质的语句放在 git commit message 里供人 blame 看。
    jsonline
        38
    jsonline  
       2014-04-03 18:06:56 +08:00
    If you see such comments in someone's code, it may imply that
    1. the function is bloated.
    2. he takes no advantage of SVN or GIT
    icyalala
        39
    icyalala  
       2014-04-03 18:59:17 +08:00
    1.代码是给人看的,总有某段代码不容易被理解,加上注释会更友好、理解更迅速。
    不加注释能不能看懂是另外一回事了。
    2.modified by xxx at xxx这种。。只能说版本控制没用好。
    wuxqing
        40
    wuxqing  
       2014-04-03 20:00:37 +08:00
    modified by xxx at xxx
    这种没啥问题,有的时候代码不是本部门维护,可能会有第三方。版本管理不一定好使
    cashplk
        41
    cashplk  
       2014-04-03 20:29:17 +08:00
    以前呆过一个公司,他们要求就是这样的。符合规则就好。好坏勿论。
    wwek
        42
    wwek  
       2014-04-03 22:00:26 +08:00
    冗余点的注释 没关系。只要不是产生混淆的注释。

    那种没注释的才是真坑爹·
    lidonghao
        43
    lidonghao  
       2014-04-03 22:06:43 +08:00
    modified by xxx @ V1.x.x
    在最上方写版本的相关信息
    loryyang
        44
    loryyang  
       2014-04-03 22:47:00 +08:00
    我遵守:无用代码就删掉的原则。因为无用代码包括注释会对其他接收人造成混淆和精神负担。一个是看着实在是费劲,我看过连续上百行被注释掉的代码,实在是崩溃了。有了版本管理器之后,删掉的代码完全可以删掉了。另外一个是可能会造成混淆,注释什么的如果需要,就要跟着代码的修改而不断升级,否则慢慢的,注释就废掉了,变成一种无用的负担。
    所以建议是少加注释,无用代码全删,代码尽量自解释,命名要长,逻辑尽量简单。复杂的内容才加注释
    likuku
        45
    likuku  
       2014-04-04 00:32:41 +08:00
    不是任何地方都有版本管理,很多时候可能需要直接面对服务器操作,可能还没带自己工作电脑,哪里去搞版本库?直接写源码里最方便了。
    kneep
        46
    kneep  
       2014-04-04 08:12:46 +08:00 via iPhone
    最烦这种到此一游的注释了,水平差的人基本都不知道有blame,水平差的人也不信任git或svn能做得更好,他们除了checkout和chechin,啥都不会,这样的人充斥了各个公司。
    Debiancc
        47
    Debiancc  
       2014-04-04 09:29:30 +08:00
    //声明 变量fuck
    var fuck={};
    azhao
        48
    azhao  
       2014-04-04 23:18:48 +08:00
    写法可以更简洁一些,但写是有必要的,很多人改代码的时候可不会去看你的svn log才会改
    poke707
        49
    poke707  
       2014-04-06 17:13:41 +08:00 via Android
    这也是解决问题一种办法,可能是历史原因导致不能做得更好。所以在我们非当事人或者是全新开始的话,看起来有点挫
    entertainyou
        50
    entertainyou  
       2014-04-06 21:49:31 +08:00 via iPad
    @bengol bream modify
    smilerhaha
        51
    smilerhaha  
       2014-04-07 10:50:47 +08:00
    支持 @wdlth的写法
    leavic
        52
    leavic  
       2014-04-07 15:47:00 +08:00
    我以前也喜欢写XXX Start,XXX End,
    不过现在比较少了,函数名写清楚点什么事都没了.
    lygmqkl
        53
    lygmqkl  
       2014-04-07 17:50:15 +08:00
    bug资料写入代码。。。 那么version control 的角色在哪里? 一个月更新2次,或者说3个月后相同功能就砍了,那么在这类代码的投入是不是太铺张了,或许写 win ios这样的系统需要这样吧。一般项目觉得没必要。
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   2751 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 10:12 · PVG 18:12 · LAX 02:12 · JFK 05:12
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.