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

注释写得太多了会挨打吗?

  •  
  •   fundebug · 2018-09-25 17:26:16 +08:00 · 12790 次点击
    这是一个创建于 484 天前的主题,其中的信息可能已经有所发展或是发生改变。

    145 回复  |  直到 2018-09-27 18:27:25 +08:00
    1  2  
    Harlaus
        101
    Harlaus   2018-09-26 11:10:10 +08:00
    注释永远不嫌多
    注释永远不嫌多
    注释永远不嫌多
    Harlaus
        102
    Harlaus   2018-09-26 11:10:35 +08:00
    注释永远不嫌多
    jacatch
        103
    jacatch   2018-09-26 11:18:11 +08:00
    其他语言我不好说,反正 java 里,如果在方法里面写注释,不单独拿出一行写,我绝对会 neng 死他
    jlyybz
        104
    jlyybz   2018-09-26 11:21:36 +08:00
    喜欢这样的人 除了特别牛的大佬 应该都不会觉得注释多
    socradi
        105
    socradi   2018-09-26 11:25:40 +08:00
    硬盘空间不足的时候可能会
    DiamondY
        106
    DiamondY   2018-09-26 11:25:40 +08:00
    注释写“太多”的话,看代码的时候翻白眼,鄙视是肯定有的,至于动不动手去打,就看心情了
    qingfengxm
        107
    qingfengxm   2018-09-26 11:27:03 +08:00
    注释多少都不怕,怕的是注释和代码版本不同步,代码是新代码注释是旧代码的注释,注释就没什么卵用了
    calpamomo
        108
    calpamomo   2018-09-26 11:35:27 +08:00
    这个应该是 JSDoc 吧,不怕的
    icySoda
        109
    icySoda   2018-09-26 11:35:55 +08:00
    写注释的三个层次:
    1. 什么代码都不写注释
    2. 什么代码都写注释
    3. 只在关键处(难理解处 /易出错处 /易混淆处)写注释



    同事也喜欢写很多注释, 还要求我也跟他一样写, 烦得要死
    200 行的代码, 500 行的注释, 而且注释跟代码还不一样.
    注释里参数是字符串类型, 代码里却是布尔类型.
    Joyboo
        110
    Joyboo   2018-09-26 12:06:43 +08:00
    多了会不会挨打我不知道,但少了肯定会挨打
    chungzhao
        111
    chungzhao   2018-09-26 12:07:59 +08:00
    适可而止
    kiinlam
        112
    kiinlam   2018-09-26 12:19:16 +08:00
    简单扼要就行,能生成文档更好,有小 demo 最佳
    zhangZMZ
        113
    zhangZMZ   2018-09-26 12:23:06 +08:00
    太多?什么是多?多少是多,多少是少?
    libook
        114
    libook   2018-09-26 12:26:11 +08:00   ♥ 1
    寻其根本,写注释是为了什么?

    对于这个问题,我的答案是:能让大多数人轻松看懂我的代码,简而言之就是提高可读性。

    而提高可读性不一定就要靠尽可能多地写注释,甚至不一定要靠注释,不管你用什么办法,只要达到了“能让大多数人轻松看懂我的代码”的目标就可以了。

    注释越多就越能越轻易看懂吗?
    不一定,像《三傻大闹宝莱坞》里主角用了一大串“定义”来描述“书”的时候,教授完全没听懂是什么。
    但有的时候算法真的非常复杂,少一点注释就解释不清楚,这时候不妨吧代码拆一拆,分段由浅及深写注释,可能效果会更好一些,想象一下如何才能给一个对物理学完全不了解的小学生讲明白相对论。
    laike9m
        115
    laike9m   2018-09-26 12:26:17 +08:00 via Android
    有比没有好。
    但更好的做法或许是让变量名本身就体现出其含义,作用。
    victorywangzhcn
        116
    victorywangzhcn   2018-09-26 12:35:56 +08:00
    此处应该 @syhily
    ica10888
        117
    ica10888   2018-09-26 13:55:47 +08:00
    不会
    wangccddaa
        118
    wangccddaa   2018-09-26 14:11:03 +08:00
    我记得有句话:真正好的代码是不需要注释的,如果你需要大量注释来解释你的代码,那说明你的代码还是不够好
    taevas
        119
    taevas   2018-09-26 14:20:53 +08:00
    @wangccddaa 说的比唱的好听,在座的都几十年开发?就算给个几十年,代码写出来不还是那 b 样嘛。加点注释很有必要
    ssynhtn
        120
    ssynhtn   2018-09-26 14:21:56 +08:00
    不会
    但是会因为进度太慢挨打
    chengkai1853
        121
    chengkai1853   2018-09-26 14:22:28 +08:00
    @easylee github 上从来没见过你说的这种 2:1 项目,还是大佬们的项目太渣了? 求给个 2:1 项目做模板看看!😝
    xifangczy
        122
    xifangczy   2018-09-26 14:29:33 +08:00
    略多了点,精简下语言 还行。
    tonychow
        123
    tonychow   2018-09-26 14:29:44 +08:00
    如果遗留了旧实现的注释或者忘了更新就会被打
    jmk92
        124
    jmk92   2018-09-26 14:34:44 +08:00
    让我想起来,过去一同事,工作提前做完做完了没事干,疯狂写注释。
    wolfie
        125
    wolfie   2018-09-26 14:39:22 +08:00
    就喜欢这种注释多的。

    调用没有注释的烂代码,不知道要浪费多少时间。
    whnzy
        126
    whnzy   2018-09-26 14:39:43 +08:00
    每行 79 个字符(逃
    maemolee
        127
    maemolee   2018-09-26 14:40:38 +08:00
    不嫌麻烦的话,最好能把注释写的淋漓尽致的,别人看起来方便。
    pynix
        128
    pynix   2018-09-26 14:48:17 +08:00
    很多代码可以自注释就不用写了。。
    jones
        129
    jones   2018-09-26 14:55:23 +08:00 via Android
    翻翻开源项目的源代码,spring, hibernate 这些,注释通常都比代码行数多,尤其是 public 的 API,
    easylee
        130
    easylee   2018-09-26 14:58:36 +08:00 via Android
    @chengkai1853

    非常抱歉,是我的错误,没有指明这个比例的出处。
    1/2 的比例是我在很久以前的代码规范的书本上看到的,那本册子我已经找不到了。

    不过内容依稀记得,你所指的 git 上面的来源项目注释不多,可能大多因为有手册或者文档,并未做成注释。
    pkoukk
        131
    pkoukk   2018-09-26 15:03:36 +08:00
    不会挨打,但是你这样写的问题是,如果你的函数修改了,还有一大片文档要改,如果改函数不改文档,会被打死。还不如不写
    konakona
        132
    konakona   2018-09-26 15:41:56 +08:00
    你这个还只是变量注释。变量有注释很重要哦!
    konakona
        133
    konakona   2018-09-26 15:42:36 +08:00
    这样写严格来说是不规范的,IDE 不友好。
    比如说我再其他地方或者这个文件的下面,按 ctrl 剑鼠标放在变量上面,并不能出现完整的注释内容哦。
    请按照规范写。
    init
        134
    init   2018-09-26 15:58:27 +08:00
    讲真 我觉得真的是挺好的
    wobuhuicode
        135
    wobuhuicode   2018-09-26 16:07:51 +08:00
    JSer。 做了一段时间 OC 之后,注释少了,但是函数名长了
    dychenyi
        136
    dychenyi   2018-09-26 16:16:32 +08:00
    doxgen 生成一份详细开发说明书就是这么写的。 好多开源类的文档就是这么来的
    YzSama
        137
    YzSama   2018-09-26 16:25:02 +08:00 via iPhone
    你排下版, 比如 注释文字对齐
    ashe
        138
    ashe   2018-09-26 16:54:36 +08:00   ♥ 4
    让各位见笑了。这幅图的出处是我写的代码。
    我不但有写注释的习惯,还有写文档的怪癖。
    除了这个注释,我还配了一个上万字的文档..........
    图略大。http://alonesuperman.com/statics/imgs/doc.png
    xiaoyang7545
        139
    xiaoyang7545   2018-09-26 16:56:46 +08:00
    我觉得没问题,主要注释没有干扰到代码的阅读。
    jasonyang9
        140
    jasonyang9   2018-09-26 17:01:16 +08:00
    注释和代码对不上,一定以及肯定会被打死
    nikymaco
        141
    nikymaco   2018-09-26 17:03:38 +08:00
    这个注释写得挺好。把参数来意,方法逻辑在规范的地方写上了特别有助于团队开发。如果是写过多注释在方法体内就变成除臭剂了,这样就不太好了,代码阅读起来费劲。不过这一切都是团队一起规范起来才行,方法体有变更就要即时更新注释,特别是有些家伙改了你的东西没有即时更新,那就操蛋了,哈哈。
    swim2sun
        142
    swim2sun   2018-09-26 17:05:06 +08:00   ♥ 1
    建议不嫌注释多的看看《 clean code 》。
    注释维护起来是比较麻烦的,一旦代码改了注释没同步更改,这不会影响编译和测试,但隐患就产生了,错误的注释还不如没有注释。
    合适的变量名、方法名远比注释有用
    young7657
        143
    young7657   2018-09-26 17:28:13 +08:00
    把注释当成文档来写也不太好吧
    fundebug
        144
    fundebug   2018-09-26 20:11:55 +08:00
    @swim2sun 《 clean code 》果然精辟,变量名和方法名确实得花点心思,不能随便取!
    zky001
        145
    zky001   2018-09-27 18:27:25 +08:00
    能说清楚就好啦!
    1  2  
    关于   ·   FAQ   ·   API   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   762 人在线   最高记录 5168   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.3 · 28ms · UTC 21:06 · PVG 05:06 · LAX 13:06 · JFK 16:06
    ♥ Do have faith in what you're doing.