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

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

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

    145 条回复    2018-09-27 18:27:25 +08:00
    1  2  
    whypool
        1
    whypool  
       2018-09-25 17:33:54 +08:00
    会,把注释当文档了
    pain400
        2
    pain400  
       2018-09-25 17:34:17 +08:00
    挺好的
    orange1818
        3
    orange1818  
       2018-09-25 17:36:10 +08:00
    我已经备好手枪了
    easylee
        4
    easylee  
       2018-09-25 17:37:56 +08:00 via Android
    一份经久不衰的代码,注释量与代码量的比应该至少为 2:1。
    fundebug
        5
    fundebug  
    OP
       2018-09-25 17:39:01 +08:00   ❤️ 1
    @orange1818 《刑法》第一百二十八条第一款的罪名为非法持有、私藏枪支、弹药罪。该款规定:违反枪支管理规定,非法持有、私藏枪支、弹药的,处三年以下有期徒刑、拘役或者管制;情节严重的,处三年以上七年以下有期徒刑。
    smilepig
        6
    smilepig  
       2018-09-25 17:39:05 +08:00
    详细点是蛮好的。。。
    wupher
        7
    wupher  
       2018-09-25 17:40:04 +08:00   ❤️ 7
    别的都还好,console.warn 我笑了
    Mariano
        8
    Mariano  
       2018-09-25 17:40:11 +08:00
    随便看了一眼,密密麻麻的字看的我头疼
    yulitian888
        9
    yulitian888  
       2018-09-25 17:41:54 +08:00   ❤️ 2
    不写注释才会被打呢
    比如下面这样的:

    /*

    +---------------+
    | |
    | 本数据库操作类 |
    | |
    +--+--+---------+
    | ^
    v |
    |
    +-----+---------+
    | |
    | 数据库 |
    | |
    | |
    +---------------+



    */
    ranoff
        10
    ranoff  
       2018-09-25 17:45:49 +08:00
    个人觉得的有点多
    zhangjiabin1010
        11
    zhangjiabin1010  
       2018-09-25 17:46:40 +08:00
    喜闻乐见啊,多写点注释,方便你我他
    yangxiongguo
        12
    yangxiongguo  
       2018-09-25 17:48:04 +08:00
    导出一下就是文档了啊
    kios
        13
    kios  
       2018-09-25 17:48:15 +08:00
    写多了我不知道,写少了可能会被同事强杀
    keinx
        14
    keinx  
       2018-09-25 17:48:47 +08:00   ❤️ 9
    有个同事写的注释特别有意思,注释里面带了很多段子,有时候找 BUG 找的心烦,看到他的诡异注释还是挺不错的。
    depress
        15
    depress  
       2018-09-25 17:59:10 +08:00   ❤️ 5
    我要是接手一个项目注释这么详细,我会请那个人吃顿饭,而且这个注释好在是在代码块外,如果是代码中,注释比代码还多,影响阅读代码那体验就很糟了。
    mztql
        16
    mztql  
       2018-09-25 18:03:56 +08:00
    规规整整的多好啊
    janxin
        17
    janxin  
       2018-09-25 18:05:31 +08:00   ❤️ 1
    没有 fuck,表明这段注释和代码是一个人写的 XD
    HuHui
        18
    HuHui  
       2018-09-25 18:08:04 +08:00 via Android
    工作严重不饱和
    SamsonWang
        19
    SamsonWang  
       2018-09-25 18:08:12 +08:00
    注释详细点挺好的
    maichael
        20
    maichael  
       2018-09-25 18:10:26 +08:00
    jsdoc 的话,选填属性应该这么写

    ```
    @param {string} [somebody] - Somebody's name.
    ```
    zhangyichent
        21
    zhangyichent  
       2018-09-25 18:16:17 +08:00
    整整齐齐的没人不喜欢,怕的是乱七八糟不知所谓的注释。。。
    endlessing
        22
    endlessing  
       2018-09-25 18:26:07 +08:00   ❤️ 1
    注释不嫌多,怕的是啰嗦表述不清的
    zwwhdls
        23
    zwwhdls  
       2018-09-25 18:28:05 +08:00
    @yulitian888 写了注释,跟代码不一样才会被打呢
    param
        24
    param  
       2018-09-25 18:32:24 +08:00
    那就要问问 @returns 同学了
    sampeng
        25
    sampeng  
       2018-09-25 18:32:37 +08:00 via iPhone
    这么多参数。提一个 obj 封装一下可好…
    DOLLOR
        26
    DOLLOR  
       2018-09-25 18:39:39 +08:00 via Android   ❤️ 1
    注释跟代码不一致,误导读者的,才会被打。
    zjp
        27
    zjp  
       2018-09-25 18:43:04 +08:00 via Android
    mockio 推崇注释即文档,异常信息还带正确示范
    anyele
        28
    anyele  
       2018-09-25 18:48:48 +08:00 via Android
    挺好的,
    moresteam
        29
    moresteam  
       2018-09-25 18:56:26 +08:00 via Android
    0 注释的路过
    hheedat
        30
    hheedat  
       2018-09-25 18:58:41 +08:00
    我觉得还行
    zwh2698
        31
    zwh2698  
       2018-09-25 19:06:07 +08:00 via Android
    有枪🔫
    firenine
        32
    firenine  
       2018-09-25 19:06:16 +08:00
    这就体现 ts 的好处了,不用写这种注释
    way2create
        33
    way2create  
       2018-09-25 19:08:32 +08:00
    想起了上次那个画注释的帖子
    cjpjxjx
        34
    cjpjxjx  
       2018-09-25 19:10:46 +08:00 via iPhone   ❤️ 2
    这是前人栽树后人乘凉,比前人挖坑后人骂娘好多了
    tangweihua163
        35
    tangweihua163  
       2018-09-25 19:19:27 +08:00
    参数这么多…就不是注释的问题了…
    kerr92
        36
    kerr92  
       2018-09-25 19:29:35 +08:00
    像 20 楼说的,string/boolean/number 一般首字母小写,optional 的属性一般用中括号括起来。
    fademeter
        37
    fademeter  
       2018-09-25 19:31:03 +08:00 via Android
    至少不会枪毙。
    zcjfesky
        38
    zcjfesky  
       2018-09-25 19:32:35 +08:00 via Android
    当你接盘别人的项目的时候就知道这种耐心注释的选手简直就是天使…
    zhzer
        39
    zhzer  
       2018-09-25 19:32:54 +08:00
    实在看不下去,可以让 ide 隐藏注释嘛
    flight2006
        40
    flight2006  
       2018-09-25 20:36:04 +08:00
    注释是好习惯,这个注释明显啰嗦了,‘一般 xxx ’后面的都可以省略,说了等于白说
    entimm
        41
    entimm  
       2018-09-25 21:01:34 +08:00 via Android
    把代码写成白话文不是更好吗
    Yuicon
        42
    Yuicon  
       2018-09-25 21:04:22 +08:00
    这么一看 java 虽然啰嗦点 但是可以少写很多 ‘注释’
    sonyxperia
        43
    sonyxperia  
       2018-09-25 21:08:19 +08:00
    我觉得挺好
    lightening
        44
    lightening  
       2018-09-25 21:09:56 +08:00   ❤️ 1
    信息太多会让真正重要的信息无法找到
    wsxyeah
        45
    wsxyeah  
       2018-09-25 21:17:32 +08:00
    命名很重要,窃以为见名知意要比写一大堆冗余的注释要好得多
    xuanbg
        46
    xuanbg  
       2018-09-25 21:23:01 +08:00
    挺好的,排版再对齐一下就更好了。
    oxoxoxox
        47
    oxoxoxox  
       2018-09-25 21:26:52 +08:00 via Android
    这种注释挺好的 标准做法 直接就能导出成文档了 应该鼓励
    乱写注释才会被人打
    fundebug
        48
    fundebug  
    OP
       2018-09-25 21:28:57 +08:00
    @lightening 注释应该言简意赅!
    framehouse
        49
    framehouse  
       2018-09-25 22:13:26 +08:00 via iPhone
    有点啰嗦,不过看十行弱智注释也好过看一行莫名其妙的代码
    gbin
        50
    gbin  
       2018-09-25 22:20:58 +08:00 via Android
    @sampeng 参数 option 本身就是一个对象
    neilp
        51
    neilp  
       2018-09-25 22:31:15 +08:00
    太闲 了
    bfpiaoran
        52
    bfpiaoran  
       2018-09-25 22:37:16 +08:00
    我咋觉得遇到这种开发就该嫁了呢
    catror
        53
    catror  
       2018-09-25 22:41:16 +08:00 via Android
    写给别人使用的接口就应该写这样的注释,然而,你会发现调用接口的人还是会来问你 :|
    PP
        54
    PP  
       2018-09-25 22:41:37 +08:00
    可以直接加薪。
    lijun0926
        55
    lijun0926  
       2018-09-25 23:04:29 +08:00 via iPhone
    挺规范
    hellodigua
        56
    hellodigua  
       2018-09-25 23:05:50 +08:00
    学习了……
    hotsymbol
        57
    hotsymbol  
       2018-09-25 23:07:56 +08:00
    看的想死
    imn1
        58
    imn1  
       2018-09-25 23:10:52 +08:00
    挨打是小事……
    nodin
        59
    nodin  
       2018-09-25 23:15:11 +08:00 via Android
    简洁明了的注释没人不喜欢,外行人也能看明白这代码用来做什么的注释肯定是好注释。
    jmc891205
        60
    jmc891205  
       2018-09-25 23:23:50 +08:00   ❤️ 2
    時間久了發現實現和註釋不一樣了:(
    fyibmsd
        61
    fyibmsd  
       2018-09-25 23:26:30 +08:00
    你已经是个死人了
    SoulGem
        62
    SoulGem  
       2018-09-25 23:39:20 +08:00 via iPhone
    有点多说实话,这种 option 的注释写成文档会好一点。
    scys
        63
    scys  
       2018-09-25 23:54:07 +08:00
    不要对一个参数写三行注释就行。
    一页纸有 80%都是注释的代码,我看不下去。
    northernlights
        64
    northernlights  
       2018-09-26 00:04:36 +08:00 via Android
    这是在写代码还是在写注释呢?垃圾代码写的注释再多也是垃圾代码,好代码不写注释也能让人一眼明白作者的思路。
    looseChen
        65
    looseChen  
       2018-09-26 00:44:01 +08:00
    @northernlights 你能够一眼分辨出别人拉出来的屎? 抱歉 话有点糙
    kslr
        66
    kslr  
       2018-09-26 00:55:02 +08:00 via Android
    我只会写思路和需要注意的部分
    RockShake
        67
    RockShake  
       2018-09-26 08:21:54 +08:00
    注释可以直接生成文档的,你这样省了写文档的工作,不是挺好的么,Java 代码大部分文档不都这样生成的么,一堆人连编程规范都没读过吧。
    Howlaind
        68
    Howlaind  
       2018-09-26 08:45:04 +08:00 via Android
    干脆搞文学式编程得了
    bk201
        69
    bk201  
       2018-09-26 08:47:24 +08:00
    维护起来相当麻烦,注释不应该面面俱到,应该关注重点.
    Lawlieti
        70
    Lawlieti  
       2018-09-26 09:14:09 +08:00
    出来挨打
    MaxTan
        71
    MaxTan  
       2018-09-26 09:30:11 +08:00
    文档注释写再多都不怕。
    a = 1; //给变量 a 赋值 这种直接打死
    allgy
        72
    allgy  
       2018-09-26 09:31:44 +08:00
    代码不够注释凑
    aaronysj
        73
    aaronysj  
       2018-09-26 09:32:24 +08:00
    参数是不是有点多
    wqzjk393
        74
    wqzjk393  
       2018-09-26 09:36:25 +08:00   ❤️ 1
    flask 源码了解下。。满屏幕的注释
    psklf
        75
    psklf  
       2018-09-26 09:39:00 +08:00
    我推荐多写注释,越详细越好。
    zhaogaz
        76
    zhaogaz  
       2018-09-26 09:44:41 +08:00
    最好写成类似 javadoc 的那种,能直接生成文档。

    其他的注释只保留极少部分 必要的就够了。

    能做到以上 2 条的,基本是很优秀了。
    kingwl
        77
    kingwl  
       2018-09-26 09:46:38 +08:00   ❤️ 2
    gesse
        78
    gesse  
       2018-09-26 09:50:36 +08:00
    下注释的习惯是好的, 不过这个代码能力有待商榷
    TomatoYuyuko
        79
    TomatoYuyuko  
       2018-09-26 09:50:44 +08:00
    同步 xhr 要被封杀么,哪里的消息
    fundebug
        80
    fundebug  
    OP
       2018-09-26 09:57:03 +08:00
    ben1024
        81
    ben1024  
       2018-09-26 09:57:19 +08:00
    不推荐写注释,写注释是因为看代码不知道在做什么
    zsy979
        82
    zsy979  
       2018-09-26 10:01:32 +08:00
    如果注释跟代码是一致的请他吃饭啊
    Linxing
        83
    Linxing  
       2018-09-26 10:01:57 +08:00
    你敢不写试试?
    Edwards
        84
    Edwards  
       2018-09-26 10:06:01 +08:00
    接受代码写得不好,但是不接受文档写的不好的,同理注释。
    NicholasYX
        85
    NicholasYX  
       2018-09-26 10:11:46 +08:00
    一打眼就能看明白的没有必要写注释吧……
    xpresslink
        86
    xpresslink  
       2018-09-26 10:14:33 +08:00
    @fundebug
    python 有一个专门生成文档的工具叫 sphinx,自己从代码中抽取注释生成结构化的 HTML 文档。
    flask 的文档就是这么生成的。
    好处是文档和代码是在一起的便于维护更新,每个人在代码里写自己的文档就好了。
    最后只要生成一下就是最新的文档了,不用费力有专人去维护文档的一致性。
    q397064399
        87
    q397064399  
       2018-09-26 10:18:49 +08:00
    @fundebug #80 Python 没有注释 就没法合作了,这种动态语言 是真的令人难受
    brondogk886
        88
    brondogk886  
       2018-09-26 10:18:59 +08:00
    这么全面的注释,不维护的话估计会被人打死
    xxl11231220
        89
    xxl11231220  
       2018-09-26 10:19:22 +08:00
    求之不得。表示嫌弃不写少些注释的
    FifiLyu
        90
    FifiLyu  
       2018-09-26 10:28:53 +08:00
    代码应该做到自解释,你这样如果精力不够时,很容易出现注释和代码不同步,最终更加误导人。
    junbaor
        91
    junbaor  
       2018-09-26 10:32:56 +08:00
    看起来这是个稍微底层的方法,这注释写的,完美~
    northernlights
        92
    northernlights  
       2018-09-26 10:35:00 +08:00
    @looseChen 我可没这本事,看来你经验丰富,你自己去吃吧。
    tiedan
        93
    tiedan  
       2018-09-26 10:37:48 +08:00
    待过一家公司都不让写注释
    noNOno
        94
    noNOno  
       2018-09-26 10:38:16 +08:00
    还是蛮好的
    ioth
        95
    ioth  
       2018-09-26 10:39:02 +08:00
    我会比较尊重这样的孩子。
    Mavious
        96
    Mavious  
       2018-09-26 10:48:46 +08:00
    作为新手,最喜欢注释多多的代码了,每一行的功能都能靠注释看懂。
    多多益善。
    ljspython
        97
    ljspython  
       2018-09-26 10:49:37 +08:00
    注释永远不嫌多
    nomemo
        98
    nomemo  
       2018-09-26 10:49:51 +08:00
    挺不错的,就是要持续维护
    AllenW
        99
    AllenW  
       2018-09-26 10:52:34 +08:00
    这注释 厉害了
    sorra
        100
    sorra  
       2018-09-26 10:55:28 +08:00
    写错了才挨打
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   3295 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 34ms · UTC 10:54 · PVG 18:54 · LAX 03:54 · JFK 06:54
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.