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

同事写的注释实在太多余了

  •  2      
  •   wuzhouhui · 2020-08-23 13:18:32 +08:00 · 16666 次点击
    这是一个创建于 1551 天前的主题，其中的信息可能已经有所发展或是发生改变。
    例如声明变量和函数之前, 都要写一行注释

    // 声明变量
    // 声明函数

    大家都是成年人, 哪有人不知道这是在声明, 至于写个注释吗? 放锁写个注释, 解锁再写个注释. 都三十好几的人了, 也不看看其他人是怎么写代码的, 都说了不要写多余的注释, 还不肯改
  • 注释
  • 函数
  • 变量
  • 声明
    103 条回复  •  2020-08-27 15:08:19 +08:00
    1  2  
    ❮ ❯
    constexpr
        1
    constexpr  
       2020-08-23 13:20:48 +08:00 via Android
    强迫症吧
    kaiki
        2
    kaiki  
       2020-08-23 13:21:32 +08:00   ❤️ 10
    真没必要拿出来说吧，愿意把注释写成说明书的人真不多了。
    democracier
        3
    democracier  
       2020-08-23 13:32:48 +08:00 via Android   ❤️ 93
    多了嫌冗余，少了嫌不清晰 真难伺候
    inwar
        4
    inwar  
       2020-08-23 13:33:44 +08:00 via Android   ❤️ 1
    ide 自动生成的吧
    chinvo
        5
    chinvo  
       2020-08-23 13:34:27 +08:00 via iPhone   ❤️ 14
    这种就明显是“没意义的注释”

    注释应该是对难懂逻辑的说明
    qsnow6
        6
    qsnow6  
       2020-08-23 13:35:30 +08:00
    愿意写就算及格了，至于写的是否足够简洁、易懂，要经过长期刻意练习才能做到。
    Jooooooooo
        7
    Jooooooooo  
       2020-08-23 13:38:07 +08:00
    有注释总是比没有好
    Procumbens
        8
    Procumbens  
       2020-08-23 13:40:27 +08:00   ❤️ 2
    https://www.reddit.com/r/ProgrammerHumor/comments/i4v6b2/comments/
    莫名想到了之前 Reddit 看到的 ProgrammerHumor 里的一则帖子 hhh
    leafre
        9
    leafre  
       2020-08-23 13:42:59 +08:00
    不写可以了吧
    finab
        10
    finab  
       2020-08-23 13:46:06 +08:00
    我的配色注释是灰色，代码颜色是亮色系。
    我阅读代码时基本感觉不到注释的存在，写啥都行，推荐试试
    Vegetable
        11
    Vegetable  
       2020-08-23 13:49:24 +08:00
    为了注释而注释，脑子不清楚的表现。
    nicevar
        12
    nicevar  
       2020-08-23 13:51:10 +08:00
    如果有 sonar 检查，这样是很正常的操作
    CEBBCAT
        13
    CEBBCAT  
       2020-08-23 13:51:23 +08:00 via Android   ❤️ 11
    https://www.v2ex.com/t/661193
    https://www.v2ex.com/t/661196
    https://www.v2ex.com/t/700675

    从节点的选择中，确实能感受得到楼主对真理的追求
    anguiao
        14
    anguiao  
       2020-08-23 13:54:31 +08:00 via Android
    感觉我遇到的同事，大部分都是以下两种：
    1.无用注释一堆，代码该看不懂的还是看不懂；
    2.基本上没几句注释，但代码条理还算清晰，耐心看还算能看懂。
    代码写得好、注释又清晰的，是真的少，可能我身边的人都太菜了吧。
    wangzp0303
        15
    wangzp0303  
       2020-08-23 14:28:22 +08:00 via Android
    才知道还有个“签证”区，话说代码相关的讨论为啥放“签证”区
    rouzip
        16
    rouzip  
       2020-08-23 14:34:40 +08:00   ❤️ 3
    每个人状态不同，能力不同对于同段代码的理解也不同，需要看懂的时间也不同。注释不仅仅是规范化输入输出，更是清晰地告诉后来人，这个函数是什么，预期结果如何等等，让后人更加快速地了解这个函数，如果每个人都是 super star 级别的，全程跟项目，注释作用可能不明显，但是对于新人或者刚接触某个大型工程，可以让别人更好上手，省去大量时间看代码，跳逻辑。刚入行的实习新人，欢迎大家指正。
    louishwh
        17
    louishwh  
       2020-08-23 15:17:13 +08:00 via iPhone
    总比一行不写的强，有的不加注释自己写的都看不懂
    laike9m
        18
    laike9m  
       2020-08-23 15:27:01 +08:00 via Android   ❤️ 1
    不要光说，代码放出来看一下就知道多不多余了。一般而言如果确实只写了你说的这几个字，那确实多余。
    lithbitren
        19
    lithbitren  
       2020-08-23 15:29:04 +08:00
    声明变量是挺多余的

    声明 XX 变量有时候还是需要，光靠变量名很多时候不能一眼推断出是干啥的变量
    lzlee
        20
    lzlee  
       2020-08-23 15:31:50 +08:00
    所以这个人代码质量怎么样
    他的注释影到底影响了什么
    你给他提了明确的文档标准吗
    fffang
        21
    fffang  
       2020-08-23 15:50:24 +08:00
    @lithbitren 一般不是直接写 //XX （用途）吗，真有人会写“声明”“变量”吗？
    lithbitren
        22
    lithbitren  
       2020-08-23 16:03:42 +08:00
    @fffang 变量还行，反正写上用途就行，多写几个字把句子补完也无妨，函数光写用途关键字有时候也搞不清楚
    gdzzzyyy
        23
    gdzzzyyy  
       2020-08-23 16:06:52 +08:00
    我觉得挺好的。又不耽误你什么事情。个人习惯而已，而且这个习惯还是好习惯。
    wellsc
        24
    wellsc  
       2020-08-23 16:12:27 +08:00 via iPhone
    等接手没有注释的代码，加班加到吐，你就不会这么说了
    Maboroshii
        25
    Maboroshii  
       2020-08-23 16:17:40 +08:00
    针对这一点来说，的确是多余注释
    imn1
        26
    imn1  
       2020-08-23 16:24:52 +08:00
    多余，是因为他的变量命名规范

    如果
    a=
    a1=
    a2=
    ……
    估计你也坐不住，要动手加注释
    taogen
        27
    taogen  
       2020-08-23 16:49:46 +08:00
    无可厚非。

    他愿意加是他的事，无论是充满毫无意义的注释，还是没有任何注释，代码要看还是得看。
    tinycold
        28
    tinycold  
       2020-08-23 17:32:17 +08:00 via Android   ❤️ 3
    上 V 站的吐槽这么铿锵有力，不知道你有没有当面给到他 feedback，在 code review 中，或是私底下。

    如果有，那我支持你。
    如果没有，我觉得就本质上大家都没啥区别，就是领工资混日子罢了，你对他的吐槽也不是出于对"高可读"代码的追求。
    YaakovZiv
        29
    YaakovZiv  
       2020-08-23 17:46:32 +08:00
    @imn1 太真实了，如果是解释一下变量命名给谁用的，我觉得可以理解。
    binjoo
        30
    binjoo  
       2020-08-23 17:56:31 +08:00   ❤️ 7
    程序员两个不喜欢：

    1. 不喜欢写注释；
    2. 不喜欢别人不写注释；
    aliveyang
        31
    aliveyang  
       2020-08-23 18:48:26 +08:00
    可能他是先写注释，理清思路再写代码吧
    aliveyang
        32
    aliveyang  
       2020-08-23 18:49:57 +08:00
    应该是个习惯问题
    zhenghuiy
        33
    zhenghuiy  
       2020-08-23 18:58:20 +08:00 via iPhone   ❤️ 6
    楼主就不该来这里吐槽，看到那些评论是不是更生气了。🤣

    同时也吐槽，楼上几个连客观的对错都不分了么。。明显无意义的注释都能杠一下「等碰到不写注释的就有你受的了」—— 生活虽苦但自己对于优劣的标准不能放弃呀。
    jerryrib
        34
    jerryrib  
       2020-08-23 19:03:13 +08:00
    ![111122554.png]( https://i.loli.net/2020/08/23/RhJdXzvu1KFQrjI.png)
    joiejia
        35
    joiejia  
       2020-08-23 19:26:52 +08:00
    代码也不一定都是给同行看的。我做 seo 的，不会写代码，只看得懂工作相关部分，有时候看网页代码还能不能再优化精简时，有注释是能帮到我的。
    windfarer
        36
    windfarer  
       2020-08-23 19:49:16 +08:00 via Android
    你见过用日语写注释的就不会有这么多抱怨了
    uiosun
        37
    uiosun  
       2020-08-23 19:55:07 +08:00
    @chinvo

    “难懂逻辑”——这四个字几乎概括了从萌新到大牛，一路上所有的逻辑，毕竟与其你按自己水准来断定“难懂逻辑”，不如写全点。

    就怕这个哥们一天代码 50 行，剩下时间都顾着写逻辑了……
    Felldeadbird
        38
    Felldeadbird  
       2020-08-23 20:55:26 +08:00 via iPhone
    有可能是 ide 自动生成。
    Seanfuck
        39
    Seanfuck  
       2020-08-23 21:00:32 +08:00 via iPhone
    变量名和函数名用英文写清楚，就不需要注释，写了多余
    guanhui07
        40
    guanhui07  
       2020-08-23 21:04:32 +08:00
    程序员两个不喜欢：

    1. 不喜欢写注释；
    2. 不喜欢别人不写注释；
    watzds
        41
    watzds  
       2020-08-23 21:16:35 +08:00 via Android
    过犹不及，这也是坏习惯，不是什么至少比不写好

    精力花在这地方，代码命名不知道怎么样
    LifStge
        42
    LifStge  
       2020-08-23 21:20:58 +08:00
    @taogen 确实啊 不过也不是完全无意义的事情啊 在大量代码中 一眼中文 看出这个代码是干嘛的 不是更轻松么 具体不知道什么语言的代码 有时候还是很必要的 这样一眼看出来 肯定要比 虽然是特别简单的 但是还是要分析下上下代码才能看出来具体的意义强一些啊
    还有就是习惯问题 很多时候用注释做下比较简单的分割 具体也没啥意义 随手就把当下的简单的写上也无可厚非

    咋那么多 动不动就上纲上线的呢 是不是不符合自己规范的代码都是 XXXX 呢.....
    LifStge
        43
    LifStge  
       2020-08-23 21:22:14 +08:00
    @wangzp0303 哈哈 确实 签证区 好生奇怪
    huiyifyj
        44
    huiyifyj  
       2020-08-23 21:34:32 +08:00
    go 语言规范要求只要是 export 的变量和函数都写注释，这么看来怕不是所有 gopher 都表示无辜。

    突然想起来，vscode 的 go 扩展，如果不写注释，会黄色警告⚠。
    zengguibo
        45
    zengguibo  
       2020-08-23 21:42:32 +08:00
    毕业后去了一家公司，里面的代码都没有注释，问了原来的员工，答：代码就是最好的注释
    kaedea
        46
    kaedea  
       2020-08-23 21:55:20 +08:00 via Android   ❤️ 1
    公有 API 跟 算法过程需要写注释，其他地方通过 CoseStyle 进行语义注释。
    Girlphobia
        47
    Girlphobia  
       2020-08-23 22:46:27 +08:00 via Android   ❤️ 1
    @CEBBCAT 遇到错误节点的帖子可以向管理员举报。
    dvaknheo
        48
    dvaknheo  
       2020-08-23 22:50:20 +08:00
    @zengguibo 只要这代码不刁钻。
    读代码，写得怎么样都能忍，只要关系不复杂。不能忍的三种

    这东西从哪里冒出来的。
    改了这地方，其他地方崩了
    改了其他地方，这地方崩了。

    就以我熟悉的 PHP 来说吧。
    $object->getFooByCache(); 搜一下，没引用，咔嚓了。

    等等，怎么 $object->foo 报错了。 原来是魔术调用， $object->foo <=> $object->ByCache
    52coder
        49
    52coder  
       2020-08-23 22:55:32 +08:00
    这种还好，你见过一个 3000 多行的代码，一行注释都没有的吗？真的日了狗了。
    dustinth
        50
    dustinth  
       2020-08-23 23:01:27 +08:00
    不好的注释不如不注释. 并不是比没有注释强.
    Takamine
        51
    Takamine  
       2020-08-23 23:02:46 +08:00
    诚然，注释是要做到简洁准确。
    如果说极端一点的话，我宁愿看注释内容有效，但可能有很多多余注释的代码；也不愿意看一堆吹嘘所谓的代码自述性的人写的几乎没注释，然后就算是去问写代码的，结果自己都不知道自己当时为什么要这么写的代码。
    毕竟真的要接手的时候，看着这前面搞了一波抽象之后又逻辑嵌套很深的代码，有注释是真的节约很多时间，要是当初写这代码的人都找不到了，那有注释就真是很良心了。
    optional
        52
    optional  
       2020-08-23 23:16:53 +08:00
    大部分的注释都是多余的。 命名准确就是最好的注释。
    caola
        53
    caola  
       2020-08-24 00:32:39 +08:00
    @wuzhouhui 注释多不可怕，可怕的是一个都没注释的，很多开源软件都是非常多注释的，比如：jquery
    aureole999
        54
    aureole999  
       2020-08-24 02:21:25 +08:00
    注释一般写的是目的，为什么要这么干。而不是把代码翻译成文字。
    Mutoo
        55
    Mutoo  
       2020-08-24 07:36:04 +08:00
    DOs:

    // Describe the requirement

    // How and why doing this

    // Special/Edge Cases

    // Helpful Resource: https://example.com

    /*
    * Docstring
    */

    DONTs

    // This is comment

    // This is a variable
    var foo = bar;

    // if condition do that
    if(condition) {
    // that
    }
    babyblue
        56
    babyblue  
       2020-08-24 08:06:36 +08:00 via Android
    除非你是他的上级；既然你说过一遍就不要再说了 ，除了破坏同事关系起不到任何作用，不影响代码运行就行了，你有强迫症也得给我憋回去
    Goooler
        57
    Goooler  
       2020-08-24 08:17:11 +08:00
    好的命名本身就是好的注释，你说的这种完全就是废话呗
    jiyingze
        58
    jiyingze  
       2020-08-24 08:24:02 +08:00 via iPhone
    java 代码。我见过给 setget 注释的。正常业务代码不写注释
    Daniel17
        59
    Daniel17  
       2020-08-24 08:36:41 +08:00
    唉，我现在看代码就很烦，都是 // 调用开始， // 调用结束
    xiaomingVTEX
        60
    xiaomingVTEX  
       2020-08-24 08:43:21 +08:00
    不作讨论, 推荐个文章给大家看看 [Stop Writing Code Comments]( https://blog.usejournal.com/stop-writing-code-comments-28fef5272752) (译文可搜 停止代码注释) , 或许对大家有帮助
    NotFoundEgg
        61
    NotFoundEgg  
       2020-08-24 08:53:05 +08:00
    写也不行 不写也不行
    他写这种废话注释 大概率写别的代码也会写注释
    总好过那些一点注释不写的人
    kemikemian
        62
    kemikemian  
       2020-08-24 08:53:16 +08:00
    碍着你写 bug 了?
    我反正觉得这种人很牛
    l00t
        63
    l00t  
       2020-08-24 08:55:35 +08:00
    @imn1 #26 然后他加的注释是： 声明变量 a， 声明变量 a1， 声明变量 a2……
    quan01994
        64
    quan01994  
       2020-08-24 08:56:46 +08:00
    注释还是多写一写。。业务流程一大堆的时候，你就知道注释有多么重要，当然可有可无的，也不会影响什么，
    只要不写错误的注释就行。
    12tall
        65
    12tall  
       2020-08-24 08:59:47 +08:00
    如果有很多变量放一起声明，我倒是很喜欢你同事的这种注释
    Vitta
        66
    Vitta  
       2020-08-24 09:08:20 +08:00 via iPhone
    我自己的代码我自己都看不懂，包括变量
    vipppppp
        67
    vipppppp  
       2020-08-24 09:30:42 +08:00   ❤️ 2
    不明白喷楼主的人

    无意义的东西只会增加人的阅读量，当垃圾信息越来越多，你就会不耐烦，然后可能会忽略掉重要的东西

    每个人的精力和时间都有限，不要产生垃圾信息，也不要让人阅读垃圾信息。
    bnm965321
        68
    bnm965321  
       2020-08-24 09:41:22 +08:00
    这种注释是多余的，绝不是有了比没有好，因为如果要修改代码也要去修改这些注释，就会带来多余的心智负担
    kiroter
        69
    kiroter  
       2020-08-24 09:47:08 +08:00   ❤️ 1
    这是老年人刚入门吧， 还没习惯。习惯就好了。
    shuigui
        70
    shuigui  
       2020-08-24 09:59:10 +08:00
    是不是什么基于人工智障的插件自动生成的？
    ytll21
        71
    ytll21  
       2020-08-24 09:59:52 +08:00
    写出这样注释的程序员，毫无疑问，就是水平还停留在初级阶段，需要多读书，多看别人的代码来提高自己。可以参考这篇文章，对号入座。https://www.lovelywindy.club/2020/08/24/jie-du-java-by-comparison-become-a-java-craftsman-in-70-examples/
    fx777
        72
    fx777  
       2020-08-24 10:11:31 +08:00   ❤️ 2
    我们公司 代码里边 一堆人名。。
    这些人名就是 各位产品经理的名字。。例如“2019 年 12 月 12 日 xx 产品说 这里要删掉 xxxx ”
    securityCoding
        73
    securityCoding  
       2020-08-24 10:15:13 +08:00
    @zengguibo 英文不是母语,经常词不达意的,代码即文档很难很难做到,Apache 的开源项目注释比源码还多呢
    tiedan
        74
    tiedan  
       2020-08-24 10:19:25 +08:00
    注释是解释的是用图，不是代码的翻译。 要是代码里充满了，“声明了 xx 变量”，“这里循环 XX 次，然后取 XX 字段累和”，这种注释不如不写。
    jasonding
        75
    jasonding  
       2020-08-24 10:22:52 +08:00
    有些人都不看注释，只管问。哪怕注释写的再清楚，甚至连数据库表映射模型都得挨个问，因为注释看不懂
    azkaban
        76
    azkaban  
       2020-08-24 10:26:48 +08:00
    难道是按行算钱
    goldenCold
        77
    goldenCold  
       2020-08-24 11:01:43 +08:00
    以前接手过一个项目,写的变量名是 a;b;c 这种无意义的名字,然后有注释说明 a;b;c 是什么意思。后来有人接手写了 d;e;f,轮到我改的时候，发现注释已经和变量对应不上了。只能一行行的看代码猜变量意思
    注释只是辅助作用，有最好。 主要还是代码一定要语义化，命名清晰
    edk24
        78
    edk24  
       2020-08-24 11:04:31 +08:00
    应该让他读一下 https://www.yinwang.org/blog-cn/2015/11/21/programming-philosophy

    哈哈哈
    whitev2
        79
    whitev2  
       2020-08-24 11:15:35 +08:00
    @jiyingze #58 checkstyle 要求每个方法都要有注释，然后就用插件给每个方法生成注释，为了过检查而加的
    RadishWind
        80
    RadishWind  
       2020-08-24 11:21:49 +08:00
    我也碰到过，直接回怼这么写的同学一句：“有空这么写注释，不如把变量名写的名白点”
    dodoa
        81
    dodoa  
       2020-08-24 11:52:54 +08:00
    不瞒你说，我们代码里想看到一行注释真是太难了。。两个极端啊这是
    chenyu8674
        82
    chenyu8674  
       2020-08-24 11:54:41 +08:00
    // 这是我的回帖
    zhady009
        83
    zhady009  
       2020-08-24 12:07:56 +08:00
    变量上的注释应该要说明是干嘛用的 而不是 // 声明变量
    coderunI
        84
    coderunI  
       2020-08-24 12:13:17 +08:00
    写个注释，这个也得拿出来说说吗？做你同时太难了。
    kingwl
        85
    kingwl  
       2020-08-24 12:15:09 +08:00
    ![comments]( )
    tachikomachann
        86
    tachikomachann  
       2020-08-24 12:19:16 +08:00 via Android
    不知道原来代码是怎么样的，就我的经验，这么写的人有的时候是强迫症，让大段的代码看起来有分块的感觉，可以第一眼找到某个“块”
    OHyn
        87
    OHyn  
       2020-08-24 12:34:18 +08:00 via Android
    不愿意写注释的，代码质量统一算作不及格，有愿意写的算是对得起工作了。我这有一个同事，从不写注释，现在他自己已经不知道他写的代码会怎么运行了。
    mxT52CRuqR6o5
        88
    mxT52CRuqR6o5  
       2020-08-24 12:52:43 +08:00 via Android
    这是有 78 个人认为这种注释是合理的？
    jsonfork
        89
    jsonfork  
       2020-08-24 13:35:54 +08:00
    可能是在凑代码行吧。。
    xuewuchen
        90
    xuewuchen  
       2020-08-24 13:50:24 +08:00
    注释这东西贵精不贵多，注释一些逻辑问题和函数实现意义啥的就行了。。当然我不会鄙视楼主说的写无用注释的
    Mac
        91
    Mac  
       2020-08-24 13:52:51 +08:00 via Android
    注释不是写给你看的
    newtype0092
        92
    newtype0092  
       2020-08-24 14:01:03 +08:00   ❤️ 2
    写这种注释不是因为对自己要求严格处处注释，单纯是因为这样可以不动脑子随便复制粘贴。
    这种人真的需要写注释的逻辑往往不会去管，因为需要动脑子。

    楼上某些人，明显就是不知道要动脑子的，要是全写这种注释有个二极管就控制了，干嘛养你个吃白饭的？
    luxinfl
        93
    luxinfl  
       2020-08-24 15:19:35 +08:00
    我都是写整段注释+逻辑判断在方法名上面。代码里面偶尔带上判断条件注释
    newtype0092
        94
    newtype0092  
       2020-08-24 15:23:01 +08:00
    @edk24 #78

    打开链接，从上往下看
    排版舒适
    段落合理
    通俗易懂
    由浅入深
    好文章啊好文章

    最后
    威尔史密斯！
    我是谁？我在哪？
    shm7
        95
    shm7  
       2020-08-24 15:31:50 +08:00
    毕竟写代码是一门 Art，就像画画，小学生想象力丰富一点也是可以理解的，同理；
    icenine
        96
    icenine  
       2020-08-24 15:35:25 +08:00
    这明摆着是 IDE 自动生成懒得删的，瞧给你们嘚瑟的，可算逮着个自己会的
    1534853288
        97
    1534853288  
       2020-08-24 15:39:49 +08:00
    我们这边要求每一个变量和函数都要注释
    wenlele
        98
    wenlele  
       2020-08-24 15:42:43 +08:00
    你可以做一个 code style rule 禁掉这种注释=。=
    wty
        99
    wty  
       2020-08-24 16:10:04 +08:00 via Android
    之前有个小学弟，把我代码里面的变量名全丢翻译软件里面翻译成中文然后写在注释里面，，，，想半天不知道他为啥这么干，后来跟我说他看不懂英文🤣
    a1562619919
        100
    a1562619919  
       2020-08-24 16:21:28 +08:00 via Android
    如果没有形成注释规定，这样做“无可厚非”
    1  2  
    ❮ ❯
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   960 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 42ms · UTC 21:22 · PVG 05:22 · LAX 13:22 · JFK 16:22
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.