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

诸位对“好的代码就是要注释比代码还多”这句话怎么看?

  •  
  •   nuanshen · 82 天前 · 11582 次点击
    这是一个创建于 82 天前的主题,其中的信息可能已经有所发展或是发生改变。
    155 条回复    2022-06-03 15:44:35 +08:00
    1  2  
    wasd6267016
        1
    wasd6267016  
       82 天前   ❤️ 3
    高手的好的代码是自注释的
    如果做不到,那就多写点注释吧
    NoNewWorld
        2
    NoNewWorld  
       82 天前   ❤️ 1
    这话是对普通人说的,,牛逼的人写出来的,代码就是注释
    122006
        3
    122006  
       82 天前   ❤️ 1
    自己也需要写注释给几分钟后的自己看
    yuzo555
        4
    yuzo555  
       82 天前
    某种意义上说没错,但充分性和必要性别搞反了。
    dqzcwxb
        5
    dqzcwxb  
       82 天前   ❤️ 28
    来自 java.lang.Object#toString
    hyqCrystal
        6
    hyqCrystal  
       82 天前
    看下 spring 的源码 注释确实多,挺好的
    echo1937
        7
    echo1937  
       82 天前
    高手的代码是自注释的:代码应该简洁易懂,很容易让人明白这段代码是在干什么 -- for what 。

    现实工作中代码还应该讲清楚 why ,比如一些业务逻辑的细节,这种需要文档或者注释尽可能详实完备。
    wherewhale
        8
    wherewhale  
       82 天前
    就国内这普遍风气和水平
    大部分还是要靠注释理解代码怎么跑的
    clove
        9
    clove  
       82 天前
    可阅读的代码胜过面面俱到的注释。
    retrocode
        10
    retrocode  
       82 天前   ❤️ 2
    问题在于不同人对"好"的代码定义不同, 以"好"代码为理由不写注释的人, 代码一定不是"好"的代码
    brader
        11
    brader  
       82 天前   ❤️ 36
    还注释,我没在注释里撒谎你就该偷笑了
    wqhui
        12
    wqhui  
       82 天前
    尽量让人看到函数名或者字段名就知道这是大概做什么的,注释是更详细的解释。遇到命名成屎的函数跟字段,最应做的是重名他们,而不是用一大段注释去解释
    snoopyhai
        13
    snoopyhai  
       82 天前
    多不多其实不重要. 好才关键, 如何算好?

    写清楚方法体的用途, 逻辑, 以及为什么这么做.
    还有最重要的一点. 是谁在什么时候让你这么做的.

    Jooooooooo
        14
    Jooooooooo  
       82 天前
    这和"对绝大多数人来讲, 没到拼天赋的地步"是一个道理.

    好的代码风格之类的东西当然重要, 但不如从注释入手.
    abersheeran
        15
    abersheeran  
       82 天前
    我就很少写注释。😓除非是写复杂逻辑,否则注释除了让作者和读者都费劲以外,没什么作用。
    akatquas
        16
    akatquas  
       82 天前
    代码 self-explanatory 是逻辑使然。comment 是业务缘由,也可以用来甩锅。
    gam2046
        17
    gam2046  
       82 天前   ❤️ 1
    合理。各种优秀的开源项目,都需要大量的注释和文档,Spring 全家桶,没几个人会自己看代码。Android 也同样是看文档,看方法说明就直接上去一把梭。

    其他各类语言,.net 啥的,也是以文档、注释优先。似乎只有 C/C++项目,注释量会稍微少一些。

    如果你认为自己写代码,没有注释完全也能看得懂,并且自己在一个月后还能知道当时为什么这么写,那就可以不写注释,挑战一下自己。

    我尝试过是失败了,两个月后同事问我改需求,自己都看的一愣一愣,心中暗骂自己瓜皮。
    wangtian2020
        18
    wangtian2020  
       82 天前
    前端。
    自己写的代码不写注释都能很快读懂,对自己个人来说写注释的意义不大。
    写注释的好处(作用),可以很快明白一段代码的作用,否则可能需要阅读一会。另外可以给让别人更快理解。
    不写注释的好处,省力,这点很重要,没必要上班多干没必要的活。
    团队如果有要求就写,没要求就不写,不主动写。
    cmdOptionKana
        19
    cmdOptionKana  
       82 天前   ❤️ 3
    如果问你对 “黄河之水天上来,飞流直下三千尺”,你不会分析是不是真的天上来,具体是多少尺吧?

    人类的语言有字面意思,也有修辞手法,比如一种手法叫做“夸张”。

    因此我认为,与其只看这句话的字面意思,还不如把它理解为 “注释很重要”,不需要纠结是否一定要比代码多(这也太耿直了吧!)
    Leviathann
        20
    Leviathann  
       82 天前
    库代码和业务代码不一样
    thetbw
        21
    thetbw  
       82 天前
    有些算法可能没有多少注释,变量命名清晰就行,所谓文档就是扔一篇论文给你
    daimubai
        22
    daimubai  
       82 天前
    注释只写是什么和为什么。如果函数名足够清晰,是什么也可以不写。
    zhazi
        23
    zhazi  
       82 天前
    注释本身没什么问题。可问题是百分之 90 的人不会写注释。
    我看到注释大多类似这样

    //这是一只猫
    class Cat{}
    Building
        24
    Building  
       82 天前 via iPhone
    你注释还没写完,人家需求都改了三遍了,业务类代码和人家框架类代码有什么好比的,业务类只要在有需要解释的地方注释一下为什么这么做就行了
    nothingistrue
        25
    nothingistrue  
       82 天前
    敏捷开发出来前,(瀑布式开发年代)这是金科玉律。敏捷开发出来后,这是老顽固和不懂的人才说得出来的话。这里专门指的是代码注释,不包括 Javadoc 这种文档注释。

    最后提一点,有没有注释还是好坏的差别,注释跟代码不同步,那是正常跟错误的区别。
    rrZ2C
        26
    rrZ2C  
       82 天前
    哈哈,我是真希望 aosp 注释再多一点
    zhazi
        27
    zhazi  
       82 天前   ❤️ 7
    代码谁都会看,好的注释会告诉你为什么作者会写出以下代码。而不是通过注释重新描述一遍代码
    ebushicao
        28
    ebushicao  
       82 天前
    注释多没用,写的对才有用,有些光写些废话,还不如不写。比如:const sum = a + b; // 将 a 和 b 相加
    Huelse
        29
    Huelse  
       82 天前
    如果是具有通用性或基础性的代码,当然是有用的注释越多越好
    fredli
        30
    fredli  
       82 天前
    好代码是命名规范,逻辑清楚,测试完备,bug free
    qingshuang
        31
    qingshuang  
       82 天前
    虽然我们老讲开闭原则,但是在业务开发中很多地方代码都是需要修改的,但是经常代码被改了,注释没改,这样注释反而有误导信息,所以会说用代码来代替注释。。
    Huelse
        32
    Huelse  
       82 天前
    比较赞同楼上说的,为什么要写这段代码,可能的改进或可能的问题等,而不是光写这段代码干了啥,例如:获取...,计算...
    ryougifujino
        33
    ryougifujino  
       82 天前   ❤️ 4
    业务代码注释反而应该少,且应该自注释。Clean Code 里也说到过:“我为什么要极力贬低注释?因为注释会撒谎。也不是说总是如此或有意如此,但出现得实在太频繁。注释存在的时间越久,就离其所描述的代码越远,越来越变得全然错误。原因很简单。程序员不能坚持维护注释。
    代码在变动,在演化。从这里移到那里。彼此分离、重造又合到一处。很不幸,注释并不总是随之变动——不能总是跟着走。注释常常会与其所描述的代码分隔开来,孑然飘零,越来越不准确。”

    库代码因为变动程度没那么大,而且有些文档又是根据注释来生成的,所以你会看到大段的注释。
    elintwenty
        34
    elintwenty  
       82 天前   ❤️ 8
    1. 好的开源代码尤其基础类库会写大量注释,包含如何使用、应用背景、关键依赖关系、注意事项等等
    2. 差的业务代码可能注释得不到更新,看的人看到的都是过时的、错误的注释,这样还不如没有
    3. 简单的代码一看都懂,复杂的代码没有注释、文档、流程图等确定真的可以自解释吗?
    ws52001
        35
    ws52001  
       82 天前
    理论上,开源的代码注释比较多,因为确实是想别人理解更多一点。。商业项目代码,无非就是加个码农名和更新时间,了不得加个更新目的。。
    dqzcwxb
        36
    dqzcwxb  
       81 天前
    @elintwenty #34 你把问题说清了,很多人都是不在一个频道各说各的
    libook
        37
    libook  
       81 天前
    好的代码是能让人读出智慧的,不是单纯遵循某种硬规则的。

    沟通的时候要讲究控制信息密度,信息太少无法准确传达,信息太多又难以让人提炼需要的部分,代码注释也一样。
    encro
        38
    encro  
       81 天前
    代码解析 how ,
    注释解析 why 。

    理解这句你就什么问题都解决了。
    skys215
        39
    skys215  
       81 天前   ❤️ 1
    如果注释是拿来生成文档的,那当然是越多越好吧
    不是的话,代码应该能够自表达。对于不符合常理或特殊情况才用注释解释
    自表达代码: https://book.douban.com/subject/24858418/
    SeanGeek
        40
    SeanGeek  
       81 天前   ❤️ 1
    @wherewhale 不要动不动就“国内”
    aureole999
        41
    aureole999  
       81 天前 via iPhone
    像 Spring 这种库是让其它人调用的,一般不会去看代码再去使用,这种要写,不过其实这个写的不是注释,而是文档,不然为什么叫 javadoc 。

    文档是给用户看的,注释是给自己或自己组里人看的。
    zxxufo008
        42
    zxxufo008  
       81 天前
    java 那种源码里很多是为了生成 doc 的
    bruce0
        43
    bruce0  
       81 天前
    尽量还是代码简短易懂吧, 不要瞎搞骚操作, 我们有个前同事, 用 GO 写代码很喜欢 用 interface 然后再做类型推断, 还喜欢传闭包函数, 就是他写的代码, 很多我不加断点我都不知道跑到哪了. 我还算好的, 有的同事直接看懂不

    对于一些复杂的业务逻辑, 没法简化的, 我现在都是把公式写在相关代码前面
    Seayon
        44
    Seayon  
       81 天前
    最近刚写了一段儿感觉要被同事打的注释,我就是想解释下下面那个参数什么意思。😂
    https://s1.ax1x.com/2022/05/30/XldcLt.png
    coldmonkeybit
        45
    coldmonkeybit  
       81 天前
    多写注释可以,不过有的人(我同事)改了代码不改注释的,非常离谱
    nicevar
        46
    nicevar  
       81 天前
    这是对其他人的要求,放自己身上就总觉得不合适
    Seayon
        47
    Seayon  
       81 天前
    再次尝试贴图
    ryh
        48
    ryh  
       81 天前
    看什么项目,开源的自然是越多越好;公司项目也要有标准;个人项目就无所谓了,自己懂就行
    lakehylia
        49
    lakehylia  
       81 天前
    注释不算 KPI ,代码才是 KPI 。如果想要好的注释,那把注释加入 KPI 不就行了。
    zppass
        50
    zppass  
       81 天前
    记得看过一句话,冗长复杂的代码的注释,就好像是给后面接手的人一个道歉信
    Felldeadbird
        51
    Felldeadbird  
       81 天前
    代码是进行时,注释是过去时。

    注释容易出现代码变更,但是注释没跟着改的现象。

    第一次看《 clean code 》这句话就有很深的印象。
    Orenoid
        52
    Orenoid  
       81 天前   ❤️ 6
    “好的代码不需要注释” 这句话我都快听腻了,然而很多人写的代码并不好
    aguesuka
        53
    aguesuka  
       81 天前
    实际上 5 楼的注释都是文档, 而真正的注释是代码本身. 实际上 Jdk 中从接口到 abstract class 到实现类都符合这样的表现: 注释越来越少, 代码越来越多. 总不能说接口是好代码, 而实现类不是吧.
    emberzhang
        54
    emberzhang  
       81 天前
    写注释的绩效比写代码的绩效多吗。。。
    wupher
        55
    wupher  
       81 天前
    评价代码好坏是个复杂问题。有时候,不同时代,不同价值观都可能导致评价结果出现较大偏差。

    统计注释 /代码比是个简单方案,很简单就可以通过工具来实现此目的。

    通过一个简单方案来粗暴解决一个复杂问题,这种悲剧大家还看的少了?眼前的例子还不够么?
    jishu541464750
        56
    jishu541464750  
       81 天前
    多看看大的开源库的代码就知道了,应该没人会觉得自己的代码写的比几万 star 的项目的代码更好了吧?
    lujiaosama
        57
    lujiaosama  
       81 天前
    业务代码,简练,高密度信息的注释表达清楚为什么这么做还是有必要的, 靠代码猜逻辑还是很痛苦的. 废话注释就免了, 代码有足够的抽象, 良好的命名, 就能让人一看就知道做什么了.
    a570295535
        58
    a570295535  
       81 天前
    最好是用一句话就说明白这段代码的作用,而不是废话连篇给你复制半本 txt 电子书!
    xinJang
        59
    xinJang  
       81 天前
    深表认同 方法名就是注释
    aguesuka
        60
    aguesuka  
       81 天前
    大部分语言的标准库里最复杂的算法 -- timsort. 目测代码: 注释 = 10 : 1

    https://svn.python.org/projects/python/trunk/Objects/listobject.c
    Macolor21
        61
    Macolor21  
       81 天前 via iPhone
    注释是写为什么,而不是写是什么
    AyaseEri
        62
    AyaseEri  
       81 天前
    你像 Java 那个 toString ,我表示不可以,一大片绿油油的注释里面夹点代码,readability 为负
    SheHuannn
        63
    SheHuannn  
       81 天前
    如果需要大量的注释去解释一段代码,那这段代码可能就需要重构了;好的代码,代码本身就是注释了。
    taest
        64
    taest  
       81 天前
    其实作为中国人,我对汉语的敏感度更高,所以我写中文注释,也喜欢看有注释的代码
    goobai
        65
    goobai  
       81 天前 via Android   ❤️ 1
    建议评论区的高手以后都尽量别写注释了😄
    taest
        66
    taest  
       81 天前
    方法名或者参数名写的再好,我还是不如中文注释来的敏感
    adoal
        67
    adoal  
       81 天前
    要分清以注释面貌出现、给 external caller 看的文档,和不做为文档、给 internal maintainer / reviewer 看的真正注释
    oldshensheep
        68
    oldshensheep  
       81 天前
    @AyaseEri 别说 Java 了,Java 的文档机制是很完善的,IDE 的支持也很好。楼上没有开阅读模式,而且对于标准库文档我认为越详细越好。
    chimission
        69
    chimission  
       81 天前
    @cmdOptionKana 虽然但是, 这不是一句,原文是两句
    greatbody
        70
    greatbody  
       81 天前
    对于商业项目,如果有 JIRA 或者 AzureDevOps 等卡墙支持,可以考虑在 commit 中指定卡号。这样看起来有疑问的代码就直接去看 commit 记录及相关联的卡。
    springz
        71
    springz  
       81 天前
    业务代码经常修改的不建议写注释,底层代码还是要尽量写单元测试和丰富的注释。
    Hieast
        72
    Hieast  
       81 天前
    这个得看 ROI 。
    如果一段代码预期会被很多人看,比如面向外部的、基础的、框架性质的代码,那么不仅要解释每个参数的含义,还要说明使用场景。甚至按照文档生成工具的标准单独生成文档。
    如果一段代码只有开发者看,那么把代码写好就行,实在无法自解释的逻辑加注释。
    如果一段代码除了自己谁都不看,比如就自己用的小脚本,那想怎么写怎么写。
    springz
        73
    springz  
       81 天前
    业务代码非常容易出现代码和逻辑改了,注释没同步这种事情。看做的是什么类型的。
    tkHello
        74
    tkHello  
       81 天前
    资本阶级给无产阶级灌输的观念罢了
    amwyyyy
        75
    amwyyyy  
       81 天前   ❤️ 3
    大部分人写的就是一坨屎,还以为自己是好代码不写注释。
    yuancoder
        76
    yuancoder  
       81 天前
    代码本身就在表达你的逻辑
    BigDogWang
        77
    BigDogWang  
       81 天前   ❤️ 4
    代码自注释就是扯淡,代码命名、结构好,只能自解释流程,业务细节呢?算法细节呢?不注释看毛线呢
    laviris
        78
    laviris  
       81 天前
    对这句话的理解是,需要加上限制条件“在增删改查领域”。稍微运用点算法或者设计,没有注释,也许能看懂,但是有注释可以让看懂的时间缩短到 10%内
    FreshOldMan
        79
    FreshOldMan  
       81 天前   ❤️ 1
    不少人比较高估自己拉💩的水平,不写注释,怕不是隔了一年,自己都不敢动💩
    QiuXX
        80
    QiuXX  
       81 天前
    我有强迫症就喜欢写注释
    BeautifulSoap
        81
    BeautifulSoap  
       81 天前   ❤️ 8
    说真的,你们学了这么多年业务代码,难道都理解不到代码只能告诉你做了什么,但不会告诉你为什么要这么做的道理吗?
    业务代码比注释里写做了什么,写清楚为什么要这么做,这是哪个业务逻辑。尤其是这个业务逻辑对应的资料在哪,链接在哪更加重要
    Biwood
        82
    Biwood  
       81 天前   ❤️ 3
    注释是为了解释代码本身无法表达的部份,而不是重复代码内容
    shm7
        83
    shm7  
       81 天前
    谁说了这句话,下次让他自己在头上贴一张大大的“人”字,不然大家不知道 ta 是人啊。

    然后覆盖 20000 字的当前职位职能介绍吧,否则大家不知道他是谁。下班了回家,重写 20000 字。出去玩,重写 20000 字。
    newaccount
        84
    newaccount  
       81 天前
    写的时候:注释?写个屁的注释!老子的代码是自说明的!
    读的时候:卧槽!哪个傻 X 写的代码!特么的注释都不写的啊!
    BeautifulSoap
        85
    BeautifulSoap  
       81 天前
    @BeautifulSoap 靠,怎么打字打得错误连篇,重新修正一下:

    "说真的,你们写了这么多年业务代码,难道都理解不了代码只能告诉你做了什么,但不会告诉你为什么要这么做的道理吗?
    业务代码的注释把为什么要这么做,对应的是哪个业务逻辑,这个业务逻辑对应的资料在哪写清楚更重要。”

    最近管理项目知识,深刻意识到了管理好领域知识,并将具体代码和领域知识对应起来是多么重要的一件事
    nekoneko
        86
    nekoneko  
       81 天前
    @zppass #50 这样说, 那些源码作者该负荆请罪才是.
    nightwitch
        87
    nightwitch  
       81 天前   ❤️ 1
    "好的代码不需要注释": 只适用于搬砖代码

    复杂点的算法论文十几页都不一定能讲清楚,想靠硬啃代码看懂纯属扯淡
    nanjoyoshino
        88
    nanjoyoshino  
       81 天前
    差不多,尤其是对开源代码,注释详细的读起来真的很舒服
    SimonOne
        89
    SimonOne  
       81 天前
    那你觉得业务该不该写一下在注释里呢,不写下一个顾问倒是能看懂代码,但是也许不知道这段代码是不是符合业务。
    FallenTy
        90
    FallenTy  
       81 天前
    希望你们能在半年后不看注释秒懂自己写的代码
    GeruzoniAnsasu
        91
    GeruzoniAnsasu  
       81 天前
    注释是好的
    坏注释是坏的
    比起「注释比代码多是好的」,「测试代码比逻辑代码多是好的」的准确性更好
    qingshuang
        92
    qingshuang  
       81 天前
    @Seayon 你这里用 payTime 和 id 的联合索引不就好了嘛 payTime>= AND id>
    xuanbg
        93
    xuanbg  
       81 天前
    注释就和日志一样,不好好写非但不起什么作用,反而影响到对代码的正确理解。
    luzemin
        94
    luzemin  
       81 天前
    这代码还要注释吗?注定只能 35 岁后的我自己维护

    https://imgur.com/a/zuVy8sr
    puzzle9
        95
    puzzle9  
       81 天前
    ```
    $my_girl_friend = function ($self, $girl) {
    $age = $girl->age;
    if ($age > 18 && $age < 25) {
    $height = $girl->height;
    if ($height > 150 && $height < 180) {
    $face = $girl->face;
    if ($face > 60 || !$face) {
    $money = $girl->money;
    if ($money || !$money) {
    // 性格
    $character = $girl->character;
    return $character && $self;
    }
    }
    }
    }
    };

    $girl = new Girl(...);
    ```
    zooeymango
        96
    zooeymango  
       81 天前
    代码好不好跟注释的多少不是强相关,一般来说复杂逻辑、传参是需要注释,但是这是因为代码表达不出来这些内容,如果只是单纯复述代码,那就根本不需要加,而且注释也是需要维护的,如果不能同步维护,反而是累赘
    m102
        97
    m102  
       81 天前
    做事用心吧,就像好厨师

    做饭前后的 锅 碗 瓢 盆 调 料 厨 具 都码得整整齐齐,干干净净一个道理。

    后面轮班的厨师也好开工。
    paoqi2048
        98
    paoqi2048  
       81 天前
    反正我写
    DeepRedApple
        99
    DeepRedApple  
       81 天前
    我觉得只要代码一眼能看出是什么功能的,就不用写代码,如果不是能够马上看出什么功能的,就会写代码,如果涉及到涉及设计模式之类的,也会写。
    chenmobuys
        100
    chenmobuys  
       81 天前
    没有什么事情是绝对的,话别说的太死
    1  2  
    关于   ·   帮助文档   ·   API   ·   FAQ   ·   我们的愿景   ·   广告投放   ·   感谢   ·   实用小工具   ·   2491 人在线   最高记录 5497   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 36ms · UTC 02:42 · PVG 10:42 · LAX 19:42 · JFK 22:42
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.