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

团队开发代码不爱写注释,如何解决这一困境?

  •  
  •   labulaka521 ·
    labulaka521 · 2020-10-22 23:19:40 +08:00 via iPhone · 8275 次点击
    这是一个创建于 410 天前的主题,其中的信息可能已经有所发展或是发生改变。
    刚入职不久,维护的心累,在别人的没有注释代码上加功能是真的难受

    怎么让大家对于比较复杂的逻辑习惯写上注释
    第 1 条附言  ·  2020-10-23 10:44:52 +08:00
    个个都说自已代码写的很优雅 结果一翻代码 ifelse 先循环个五六层 这就是所谓的优雅 算了 环境导致 就这样吧 自已写的 写好注释能让以后的自已或者别人看懂就行了
    127 条回复    2020-10-25 04:39:16 +08:00
    1  2  
    Hider5
        1
    Hider5  
       2020-10-22 23:26:43 +08:00
    赶快跑
    labulaka521
        2
    labulaka521  
    OP
       2020-10-22 23:31:04 +08:00 via iPhone
    @Hider5 我是真不知道是大家都是这样还是只有这里是这样
    thedrwu
        3
    thedrwu  
       2020-10-22 23:32:45 +08:00 via Android
    换 haskell,不用写注释
    kaiki
        4
    kaiki  
       2020-10-22 23:34:23 +08:00   ❤️ 1
    不写注释我昨天写的代码今天都看不懂,估计他们的代码自己不会看吧
    az467
        5
    az467  
       2020-10-22 23:35:58 +08:00   ❤️ 2
    拒绝注释比例过少的 commit 。
    labulaka521
        6
    labulaka521  
    OP
       2020-10-22 23:37:45 +08:00 via iPhone
    @az467 这我决定不了,只是刚进去的小兵 ,只能发发牢骚或者提点意见
    labulaka521
        7
    labulaka521  
    OP
       2020-10-22 23:42:59 +08:00 via iPhone
    @kaiki 哎 谁知道呢 每次改个东西 就很难受 醉了
    labulaka521
        8
    labulaka521  
    OP
       2020-10-22 23:43:17 +08:00 via iPhone
    @thedrwu 这是什么鬼
    UsherOu
        9
    UsherOu  
       2020-10-22 23:43:42 +08:00
    我们 cto 不让写注释
    labulaka521
        10
    labulaka521  
    OP
       2020-10-22 23:47:04 +08:00 via iPhone
    @UsherOu 这能给个理由吗
    billlee
        11
    billlee  
       2020-10-22 23:54:21 +08:00   ❤️ 1
    @labulaka521 #10 遇到过注释和代码不同步的,错的注释不如没注释
    labulaka521
        12
    labulaka521  
    OP
       2020-10-23 00:05:43 +08:00 via iPhone
    @billlee 改了代码 没改注释吗
    Cuo
        13
    Cuo  
       2020-10-23 00:22:49 +08:00   ❤️ 1
    @labulaka521
    可能是因为好代码本身就具有可读性吧。
    而且业务逻辑本身也不需要写在注释里。我们组的注释一般是简单描述函数功能,或者标注参数类型。
    Cuo
        14
    Cuo  
       2020-10-23 00:23:36 +08:00
    # 10 这能给个理由吗
    labulaka521
        15
    labulaka521  
    OP
       2020-10-23 00:50:27 +08:00 via iPhone
    @Cuo 好代码的确具有可读性 ,但是不是所有代码都能是好代码
    abersheeran
        16
    abersheeran  
       2020-10-23 00:53:12 +08:00
    你这个问题直接让我思绪回到一年前我还在某公司的时候……Django1.3 配上 Python2.6,业务代码就是堆,这个无可厚非,一个 URL 一个函数嘛,反正也不影响整体项目。但代码结构也是屎,统一的 JSONResponse 都没有,一个单语句的函数,非要放进一个类里去调用。注释?你想要什么注释?我提出了这个问题……被教育了一顿。我提出优化代码,我又被教育了一顿,“自然有人来做,你把业务写好就行”。
    待了一个多月,掐点看学校的实习任务完成了,直接跑路。
    qiumaoyuan
        17
    qiumaoyuan  
       2020-10-23 00:55:29 +08:00
    重构代码
    qiumaoyuan
        18
    qiumaoyuan  
       2020-10-23 00:58:50 +08:00
    写详细点吧:

    1. 代码需要注释说明代码不可读,为了让代码可读,就需要对代码进行重构。写注释本身属于重复行为——已经用代码写了一遍,再用人类语言写一遍,一处变动需要同时做两处修改。

    2. 重构代码不需要先理解原有逻辑,逻辑在重构过程中自然就能理解。
    labulaka521
        19
    labulaka521  
    OP
       2020-10-23 01:18:16 +08:00 via iPhone
    @qiumaoyuan 代码注释说明代码不可读,这我感觉有点极端了,像一些项目比如 grpc go-micro 都有每个函数或变量都有很详尽的注释,我觉得是注释是帮助来理解代码逻辑的,而不是代码不可读了,才需要注释。
    Cuo
        20
    Cuo  
       2020-10-23 01:38:26 +08:00
    @labulaka521
    #15 好代码的确具有可读性 ,但是不是所有代码都能是好代码
    review 时有读不懂的地方直接指出来让对方改。如果是比较复杂的设计则请对方连带文档一起提交。

    或者看看以前的工资单,年终奖忍一忍也就过去了(狗头)
    boris93
        21
    boris93  
       2020-10-23 01:51:53 +08:00 via Android
    我司,跨国美企,也这样
    更不用说还能见到各种匪夷所思的脱裤子放屁写法
    非英语国家的人写的注释,有可能还得琢磨一阵才能看明白

    对我来说,业务清晰(至少在我自己看来清晰)的代码我不写注释
    对于日后可能看不懂的,或者当时就玩命网上冲浪才憋出来的代码,我会写很多的注释,并且可能附上参考文档链接
    raaaaaar
        22
    raaaaaar  
       2020-10-23 07:11:53 +08:00 via Android
    找 leader ?拿个垃圾代码过去问他看不看得懂,引导他自己提出规范的重要性。
    ferock
        23
    ferock  
       2020-10-23 07:22:19 +08:00
    自己判断,代码是否可读
    技术方案文档,另外写
    代码上附上链接。

    代码定期内部 code review 。
    别人如果看不懂你的代码,那就应该附上注释,最好重构。

    所以,团队合作写代码,规范很重要!
    AkideLiu
        24
    AkideLiu  
       2020-10-23 07:55:44 +08:00 via iPhone
    换 assembly 吧,今天不写注释明天就看不懂了
    line
        25
    line  
       2020-10-23 08:20:46 +08:00 via iPhone
    大部分情况,可以用 git commit message 代替 commit 勤快点就行
    user8341
        26
    user8341  
       2020-10-23 08:22:03 +08:00
    刚入职不久就别妄想去改变公司既有的习惯。好好适应一年。
    kemikemian
        27
    kemikemian  
       2020-10-23 08:22:06 +08:00
    你待的时间久了自然也不写了,还没融入集体
    djs
        28
    djs  
       2020-10-23 08:41:56 +08:00 via iPhone
    良好的命名比瞎写的注释更优秀,前提是良好的命名
    nicevar
        29
    nicevar  
       2020-10-23 08:44:05 +08:00
    可以搭建 SonarQube 平台,提交 MR 的时候没有注释会自动拒绝
    jerryrib
        30
    jerryrib  
       2020-10-23 08:45:11 +08:00
    sexyback
        31
    sexyback  
       2020-10-23 08:51:10 +08:00
    我找了个实习的工作,go 开发,原本想来学一下 go,结果这几天看了代码之后发现一句注释也没有,唯一的注释就是 //TO DO 这个功能尚未开发,问了带我的导师他说写注释太麻烦,看变量命名和方法名就能推算出什么意思了,学习的时候不知道注释的重要,现在终于体会到了
    sexyback
        32
    sexyback  
       2020-10-23 08:51:42 +08:00
    @labulaka521 咱俩估计一样,我们公司的代码就没有注释
    labulaka521
        33
    labulaka521  
    OP
       2020-10-23 08:51:45 +08:00 via iPhone
    @djs 确实是
    但是我们这边存在的情况是有些被重构的函数 迁移的字段 但是为了兼容还是保留原有的 这些几乎都没有注释 有些时候的用老的函数 老的字段偶尔就会出现异常
    labulaka521
        34
    labulaka521  
    OP
       2020-10-23 08:53:11 +08:00 via iPhone
    @sexyback 其实 go 还好 但是我们这边是 py 吗呀 函数参数一大堆 几乎没有注释 只有追到函数内部后才可以看到这个参数的类型 是干啥的
    xianxiaobo
        35
    xianxiaobo  
       2020-10-23 08:53:12 +08:00   ❤️ 1
    你来当老板或者领导,告诉大家注释最重要,可以开发的慢,但是一定要写注释,每天快下班前由技术领导统一检查今天的代码写注释了没。
    labulaka521
        36
    labulaka521  
    OP
       2020-10-23 08:55:10 +08:00 via iPhone
    @xianxiaobo 想认真回复就认真回复 别这样阴阳怪气的 OK ?没看前面的吗?
    jorneyr
        37
    jorneyr  
       2020-10-23 08:58:40 +08:00
    把自己写的代码也像 JS minify 那样搞一下,大家一起看不懂
    Leigg
        38
    Leigg  
       2020-10-23 09:00:52 +08:00 via Android
    这个没办法,以后你会经常遇到,除非老大提出来解决,否则都是看个人心情,你现在不懂哪里就问,不过最后先看完整体逻辑,再提问,自己写好注释
    xiaoxinxiaobai
        39
    xiaoxinxiaobai  
       2020-10-23 09:02:35 +08:00 via Android
    你读一遍代码给加上注释
    notejava
        40
    notejava  
       2020-10-23 09:03:38 +08:00
    可读性强的代码就是最好的注释。如果代码本身就逻辑混乱,也别指望注释了。
    notejava
        41
    notejava  
       2020-10-23 09:05:28 +08:00
    可读性强的代码就是最好的注释。如果代码本身就逻辑混乱,别指望他能写出好的注释。
    zsyld
        42
    zsyld  
       2020-10-23 09:05:38 +08:00
    辣鸡代码才需要注释(狗头
    djs
        43
    djs  
       2020-10-23 09:07:54 +08:00 via iPhone
    @labulaka521 悲伤
    elintwenty
        44
    elintwenty  
       2020-10-23 09:09:53 +08:00
    既然制定不了规范就不要管了,比起没有注释,过时的、失效的注释是更大的灾难。如果不能保证你的、甚至因你而出现的注释鲜明有效,那么还是完全没有更好。可以尝试要不要引入一些自动化的工具来建议主管去考虑
    maddot
        45
    maddot  
       2020-10-23 09:11:36 +08:00
    函数名称就是最好的注释
    zsdroid
        46
    zsdroid  
       2020-10-23 09:12:07 +08:00   ❤️ 1
    看了上面这么多楼的发言,感觉 jdk 特别垃圾,因为注释特别多。
    4771314
        47
    4771314  
       2020-10-23 09:12:30 +08:00
    基本的注释还是要有吧,不然谁看得懂?
    代码是写给人看的,不是写给计算机看的。
    labulaka521
        48
    labulaka521  
    OP
       2020-10-23 09:14:02 +08:00 via iPhone
    @notejava 是的 但是还存在一些被重构 被迁移的字段 函数 几乎都没有注释 用了旧的函数 字段偶尔就会报错
    idoggy
        49
    idoggy  
       2020-10-23 09:14:31 +08:00 via Android   ❤️ 1
    注释基本都是用来写 why 和 how 的,很少写 what 的,看事情不要二极管
    alcoholpad
        50
    alcoholpad  
       2020-10-23 09:16:19 +08:00
    良好的函数名, 变量名 就是最好的注释, 函数尽量短小. 如果像写文章一样认真写代码, 根本不需要注释.
    毕竟代码的修改会经常忘了同步注释, 更容易让人误解.
    UmiKz
        51
    UmiKz  
       2020-10-23 09:18:34 +08:00
    开发规范做到见名知其意,注释少些,也影响不大
    watzds
        52
    watzds  
       2020-10-23 09:20:00 +08:00 via Android
    这不是挺正常吗?
    zjsxwc
        53
    zjsxwc  
       2020-10-23 09:20:39 +08:00
    除非复杂的业务逻辑我会先写注释后写代码做填空题,同时会引用产品经理具体需求描述的 issue id 方便后续跟进,还有这种复杂的业务由于不具备可复用性,我基本都是写在一个大方法里面。


    大部分时候业务逻辑等价于 4 、5 个 sql 查询的就不写注释了,这种猜都能猜到是在干什么。
    darktutu
        54
    darktutu  
       2020-10-23 09:25:40 +08:00
    我遇到过注释和代码不匹配的,更痛苦,还不如没有注释呢。
    aydd2004
        55
    aydd2004  
       2020-10-23 09:30:29 +08:00   ❤️ 4
    说真的 我给自己写的东西都加一堆注释

    这些人哪里来的勇气
    UsherOu
        56
    UsherOu  
       2020-10-23 09:30:55 +08:00
    @labulaka521 代码即注释,见名知意
    darkforest8848
        57
    darkforest8848  
       2020-10-23 09:31:59 +08:00
    @jerryrib 兄弟 bannner 能发下吗
    zhangyangkam1
        58
    zhangyangkam1  
       2020-10-23 09:34:50 +08:00
    改变不了环境可以从自己做起
    faceRollingKB
        59
    faceRollingKB  
       2020-10-23 09:36:36 +08:00
    时间不够
    JamesR
        60
    JamesR  
       2020-10-23 09:45:47 +08:00
    外包做的,时间不够嘛。
    ungrown
        61
    ungrown  
       2020-10-23 09:47:05 +08:00   ❤️ 1
    注释其实算是个历史遗留产物
    以前计算设备算力低,开发机的算力也低
    自然也没有如今功能强大的 IDE 软件辅助写代码
    所以那时候代码字词句能少就少尽量简洁
    那么代码的含义就很难从代码本身看出来,需要注释
    现如今在 IDE 的自动补全代码树监控的加持下
    长名超长名蔚然成风
    代码含义几乎可以完全通过合理命名来显示表达
    “代码即注释”
    只有很少的情况下,才不得不依靠注释进行说明,例如:
    命名无法体现含义,亦或妖码怪码 bug 码不讲道理,亦或“知其然不知其所以然”的代码
    tikazyq
        62
    tikazyq  
       2020-10-23 09:49:49 +08:00
    这种项目,当你花了半天时间读懂的时候,需求已经变了,淡定
    jatsz
        63
    jatsz  
       2020-10-23 09:50:16 +08:00   ❤️ 1
    代码不会说谎,注释会。
    hyperbin
        64
    hyperbin  
       2020-10-23 10:01:42 +08:00 via Android
    @djs 题主这情况多半还有拼音变量
    fhsan
        65
    fhsan  
       2020-10-23 10:05:30 +08:00   ❤️ 1
    @jatsz 注释才是最坑爹的地方
    751327
        66
    751327  
       2020-10-23 10:07:46 +08:00
    @jatsz 有时候宁愿相信代码
    jerryrib
        67
    jerryrib  
       2020-10-23 10:10:16 +08:00
    ligiggy
        68
    ligiggy  
       2020-10-23 10:14:49 +08:00
    理清业务逻辑可以写注释,封装接口给人用要文档。但是如果每一个函数,每一个命名都要写注释,那才是最垃圾的。代码要提升的是可读性,而不是人人口中的“注释”。
    jatsz
        69
    jatsz  
       2020-10-23 10:20:37 +08:00
    @fhsan
    @751327

    基本上问这个问题就不是代码的问题,或者说技术问题,而更多的是管理问题。用技术的方式解决管理问题其实很糟糕。
    真如楼主说的,团队强制让人写注释了,谁对注释负责,谁对代码负责。

    还记得《让子弹飞》中的六子么?当你真的遇到了问题哭着说:“你们看看看啊,我支持了一碗凉粉”。你会发现周边根本没人听你的。
    matrix67
        70
    matrix67  
       2020-10-23 10:21:59 +08:00
    上 ci,没注释拒绝合入
    xianxiaobo
        71
    xianxiaobo  
       2020-10-23 10:24:51 +08:00   ❤️ 1
    @labulaka521 我想说的是,如果你不是领导或者老板,根本没办法。写注释确实是减少了维护成本,但是增加了开发时间啊。谁来为这部分买单呢?另外,我说的确实是解决办法,不完全算是阴阳怪气。
    sunznx
        72
    sunznx  
       2020-10-23 10:24:54 +08:00
    见过 curd 还加注释的
    sunznx
        73
    sunznx  
       2020-10-23 10:25:27 +08:00
    见过 curd 还加注释的

    // 获取一个用户
    // 删除一个用户

    这种注释还不如不注释
    qiumaoyuan
        74
    qiumaoyuan  
       2020-10-23 10:32:55 +08:00   ❤️ 2
    @labulaka521 注释的作用主要是说明代码为什么要这么做,而不是描述代码在做什么。

    另外软件开发就是要极端。没有极端过,你根本不知道“中间”在哪里,不知道极端在哪,所谓的折衷、权衡都是在搞笑和自慰。
    fyooo
        75
    fyooo  
       2020-10-23 10:37:46 +08:00
    国内大环境根本解决不了,这类需要从上至下的推动的
    casillasyi
        76
    casillasyi  
       2020-10-23 10:52:19 +08:00   ❤️ 1
    代码写的一塌糊涂的,需要注释才能看懂的,你以为他注释写的你能看懂吗?
    wysnylc
        77
    wysnylc  
       2020-10-23 10:53:24 +08:00
    @qiumaoyuan #74 学数学的时候恨不得注释多的拉满,到自己写代码就觉得注释麻烦没意义笑死了
    Still4
        78
    Still4  
       2020-10-23 10:57:15 +08:00
    @darktutu 需求变了,注释没改,我们这跟没写注释是一个原因,需求压力大,很多时候上午提需求晚上上线,谁想让后来人指着自己鼻子骂呢,时间不允许没办法,优先保证东西正常,注释都是想着后面再说,一拖就没影了
    northisland
        79
    northisland  
       2020-10-23 11:04:26 +08:00
    一行注释都没有的是垃圾;不分巨细,全注释的也是垃圾。

    还是武侯祠「攻心对联」里的那一句“不审势,则宽严皆误”。

    (但对于外行领导,想通过 5 分钟 code review 就深入理解我做的事情,目测领导也是垃圾。)
    lk920724
        80
    lk920724  
       2020-10-23 11:09:44 +08:00
    这样想,没注释总比过期注释要好。
    sdushn
        81
    sdushn  
       2020-10-23 11:16:39 +08:00
    做 cr 啊,看不懂的,格式不对的都不让合入,
    djyde
        82
    djyde  
       2020-10-23 11:34:48 +08:00   ❤️ 1
    注释不是用来解释这段代码在做什么,而是告诉后来的人为什么要写这段代码。
    paoqi2048
        83
    paoqi2048  
       2020-10-23 11:35:24 +08:00   ❤️ 1
    楼上一堆洗的,希望你们以后的同事都不写注释哈
    haha512
        84
    haha512  
       2020-10-23 11:46:29 +08:00
    看了上面回答,应该把第一个设计代码要加注释的人拉出来痛打一顿。
    v2 任何一个问题下面, 总少不了一堆的“逼王之王”,为什么呢
    pangleon
        85
    pangleon  
       2020-10-23 12:01:11 +08:00
    让 AB 互相改他们之前做的大需求,然后看他们对喷
    labulaka521
        86
    labulaka521  
    OP
       2020-10-23 12:09:01 +08:00 via iPhone   ❤️ 3
    @haha512 没办法 总有人觉得我的代码很优雅 很优雅 不用注释 结果一看 是什么玩意 叠加五六层 ifelse 真逼王之王
    lululau
        87
    lululau  
       2020-10-23 12:16:45 +08:00
    业务代码不需要注释,类名和方法名就是注释,把 PRD 写写好是最重要的
    opengps
        88
    opengps  
       2020-10-23 12:26:28 +08:00
    写注释奖钱啊,很多人不写,不就是因为大部分企业都卸磨杀驴吗
    wysnylc
        89
    wysnylc  
       2020-10-23 12:29:54 +08:00
    @labulaka521 #86 你要保持这个心态,永远不要觉得自己优雅
    优雅是别人对你的评价,不是自己觉得自己多牛逼,总有些人觉得自己写点代码就人上人了莫名其妙的优越感
    不写注释的都是垃圾
    Leigg
        90
    Leigg  
       2020-10-23 12:36:21 +08:00 via Android
    楼上一帮人,个个以为光看代码就看懂了,要么是真牛逼,没遇到过垃圾同事,要么是长期混迹小公司自己就从来不写注释的,别人问还怼别人的。
    哪个比例更高一点?
    Huelse
        91
    Huelse  
       2020-10-23 13:06:51 +08:00
    当然是能一起商量好最好

    实在不行就你写的时候完全不按套路命名来写即可,注释留在自己的仓库,commit 的时候去掉注释
    zerofancy
        92
    zerofancy  
       2020-10-23 13:16:52 +08:00
    lint
    tony1890
        93
    tony1890  
       2020-10-23 13:21:48 +08:00
    没办法。只能管好自己。虽然我跟同事说过多次,不用的代码要么注释要么删除,方法最起码说明是干嘛的,公共方法还要写入参和 returns,公共组件要写文档。balabala 一堆。
    然而他们很难做到。唯一欣慰的就是提交写简短记录了。
    newmlp
        94
    newmlp  
       2020-10-23 13:26:18 +08:00
    又不是不能用
    darktutu
        95
    darktutu  
       2020-10-23 13:28:44 +08:00
    @Still4 是啊,所以我挺好奇的,一般项目的注释都很完善,只有我遇到的是乱糟糟的?还有就是单元测试,也是没多少或者没有,到那时看评论,大家经常都是齐备的,我也搞不明白。
    tabris17
        96
    tabris17  
       2020-10-23 13:29:03 +08:00
    我只在个人项目里会尽责地写注释
    troywinter
        97
    troywinter  
       2020-10-23 13:51:32 +08:00
    题外话,注释和代码有不同的目的,不存在好的代码不需要写注释的,他们的目的本来就不相同,有些简单的逻辑确实不需要注释,但大多数情况下,注释还是应该解释下这样设计的原因和用法,最好链接到设计文档。
    qiumaoyuan
        98
    qiumaoyuan  
       2020-10-23 14:01:04 +08:00
    @labulaka521 也许你见过你口里描述的人,但同时你要知道这世界上真有不少人的代码是不用注释的。把无法理解的事情打个装逼的标签,把难以实现的理想当作自己不努力的借口对自己没有好处。有理就好好讲理这是程序员的基本素养,起码冰冷的机器不会照顾你的个人情绪。
    tankren
        99
    tankren  
       2020-10-23 14:19:03 +08:00
    看可读性吧
    lazydog
        100
    lazydog  
       2020-10-23 14:24:19 +08:00
    不写注释看来是真的不行,我一周前的代码,今天看的时候竟然看不懂了,费了好长时间才反推回去。
    1  2  
    关于   ·   帮助文档   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   4048 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 03:26 · PVG 11:26 · LAX 19:26 · JFK 22:26
    ♥ Do have faith in what you're doing.