• 请不要在回答技术问题时复制粘贴 AI 生成的内容
nuanshen
V2EX  ›  程序员

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

  •  
  •   nuanshen · May 30, 2022 · 17853 views
    This topic created in 1633 days ago, the information mentioned may be changed or developed.
    155 replies  •  2022-06-03 15:44:35 +08:00
    1  2  
    ❮ ❯
    darknoll
    darknoll
    May 30, 2022
    101
    代码即注释
    yaphets666
    yaphets666
    May 30, 2022
    102
    @dqzcwxb 人家啥工期,咱啥工期啊,差不多得了
    MatrixLau
    MatrixLau
    May 30, 2022 via iPhone
    103
    @brader #11 太坏了 哈哈哈哈哈
    demonps
    demonps
    May 30, 2022
    104
    代码就是我我们交流的语言,除非异常复杂的逻辑,否则从不写注释
    fgwmlhdkkkw
    fgwmlhdkkkw
    May 30, 2022
    105
    @SimonOne #89 这是什么语言呀?
    nuanshen
    nuanshen
    OP
    May 30, 2022
    106
    @snoopyhai 领导在开会走读代码的时候提的呗,他的意思似乎是想让我们把代码翻译成中文写在注释里
    Ct5T66PVR1bW7b2z
    Ct5T66PVR1bW7b2z
    May 30, 2022
    107
    我觉得没错啊,自从用上了 copilot 之后,我就养成了写注释的习惯
    Leviathann
    Leviathann
    May 30, 2022
    108
    声明式的代码才有代码即注释一说
    全是命令式的代码一眼看过去鬼知道在干嘛,全是噪音

    因为声明式写的是 what ,而命令式写的的是 how

    这也是现代编程语言的一个进步的方向
    nuanshen
    nuanshen
    OP
    May 30, 2022
    109
    @skys215 我也是这种想法
    sky857412
    sky857412
    May 30, 2022
    110
    后端业务这么复杂,再好的代码也需要注释,今天 A1 需求,明天 A2 需求,这没有注释都看不懂
    nuanshen
    nuanshen
    OP
    May 30, 2022
    111
    @Building 嗯,认同
    asdjfuhgasiduf
    asdjfuhgasiduf
    May 30, 2022 via Android
    112
    让我想起本科时候上的软件工程课了,代码的可读性比代码的运行效率优先级更高。
    dbow
    dbow
    May 30, 2022
    113
    跟注释关系不大, 容易写测试的代码,就是好代码
    BestP
    BestP
    May 30, 2022
    114
    没有注释又能一眼读懂的代码才是好代码
    xuyang2
    xuyang2
    May 30, 2022
    115
    @Seayon
    10 也是拍脑袋,8 也是拍脑袋,
    五十步笑一百步了属于是
    ukyoo
    ukyoo
    May 30, 2022
    116
    可别吹了, 有几个能把代码写的"自解释"的, 业务代码都是很复杂的, 写注释能帮别人快速理解
    7gugu
    7gugu
    May 30, 2022
    117
    业务逻辑都要写注释,平时根本抽象不了多少代码,很多注释都是为了某次莫名的修改而增加的,不然前人离职了,代码就动不了了。
    lance1ot
    lance1ot
    May 30, 2022❤️1
    118
    实在不能苟同楼上几位“高手代码就是自注释”的观点。曾读过 MSRA 大佬的代码,觉得很头疼。我觉得不要求注释写得非常详细,只要能概述一下代码块的功能就好,说明输入输出之类的,让人知道是干什么的之后再去理解会容易很多。
    就像你读书前会看书名,而不是根据书的内容去倒推书名
    SimonOne
    SimonOne
    May 30, 2022
    119
    @fgwmlhdkkkw #105 abap
    Seayon
    Seayon
    May 30, 2022
    120
    @xuyang2 1. 的确是拍脑袋,总比不拍好。2. 没看懂
    Seayon
    Seayon
    May 30, 2022
    121
    @qingshuang 感谢指导,这样好像是可以的,不过已经有 10 个索引了太多了 😂。
    cp19890714
    cp19890714
    May 30, 2022
    122
    任何话术道理都有其对应的场景,不是万能的。
    6167
    6167
    May 30, 2022
    123
    我因为注释太多,被挂了机试
    B1ankCat
    B1ankCat
    May 30, 2022
    124
    矫枉必须过正,不过正不能矫枉
    YYYeung
    YYYeung
    May 31, 2022
    125
    注释(这里不算方法签名上的那部分)应该是写某个模块的总体思路;或某个有惊喜的地方需要稍作注明,用于提示别人或以后的自己
    而本来写在具体实现中的注释,应该通过好的变量名和方法名来体现;如果觉得其中的逻辑过于复杂,想写注释时,应该先思考一下逻辑是否可以进一步拆分
    PureWhiteWu
    PureWhiteWu
    May 31, 2022❤️1
    126
    别总把自己当高手,当牛逼的人,以为自己代码写得很漂亮,能自注释。
    不信你试试回过头去看半年前你写的代码。

    ————————————————————

    所以,多写点注释吧,把上下文说清楚,这不是留给后来人的,其实是帮助未来的你。
    不写注释的研发,一看就知道没有过大型团队协作项目的经验。
    drackzy
    drackzy
    May 31, 2022
    127
    注释写的好,老板招个实习生,学会了你就被替代了。
    pengtdyd
    pengtdyd
    May 31, 2022
    128
    注释是写给高手看的,不是写给菜鸡看的,菜鸡就算你写了,他依旧不明白
    lldld
    lldld
    May 31, 2022❤️1
    129
    @Seayon 你的需求为什么不用 payTime, id 两个来排序?
    houOne
    houOne
    May 31, 2022
    130
    @brader #11 呃呃呃,诸如 注释撒谎 变量名撒谎 表名撒谎 扩展字段偷偷使用不加注释 太多太多了。
    keenkiller
    keenkiller
    May 31, 2022
    131
    大部分情况下,这句说法是对的

    其实注释最重要的是和代码保持一致,很多人更新了代码但是不更新注释
    houOne
    houOne
    May 31, 2022
    132
    业务逻辑 /流程 注释 很重要

    代码执行操作 很轻松能看明白的 不建议 注释
    DiamondY
    DiamondY
    May 31, 2022
    133
    估计觉得这句话没问题的,都没看过流水账日记那样的代码注释吧?
    54yinhang
    54yinhang
    May 31, 2022
    134
    过犹不及
    yxzblue
    yxzblue
    May 31, 2022
    135
    谁说的?谁说的?
    Seayon
    Seayon
    May 31, 2022
    136
    @lldld 谢谢谢谢,我们考虑下加这个索引。前人这个做的,我想他考虑的是可能现有索引已经太多了( 10 个)所以不想加索引。
    getinlight
    getinlight
    May 31, 2022
    137
    只要是给时间,注释我都能写成作文。就怕既要又要还要。。。
    cominghome
    cominghome
    May 31, 2022
    138
    这句话后面代表的意思是对的,即,好的代码是要让人能看懂的,只盯着这句话就会显得太绝对
    nuanshen
    nuanshen
    OP
    May 31, 2022
    139
    @getinlight 做业务的敏捷开发,实在没多少时间,业务还多变
    w0017
    w0017
    May 31, 2022
    140
    代码写得结构清晰点,多迭代两次,尽量少用语法糖
    abolast
    abolast
    May 31, 2022
    141
    注释写到自己的笔记本上
    l00t
    l00t
    May 31, 2022
    142
    不要把注释当文档。注释取代不了文档。该写需求文档方案设计文档的时候还是得写,别以为可以放到注释里。
    macha
    macha
    May 31, 2022
    143
    注释多讲讲 why 。
    how 的话,好的代码确实是自解释的。但是 why 确实很难做到自解释。
    WOLFRAZOR
    WOLFRAZOR
    May 31, 2022 via Android
    144
    屎一样的代码没注释不是最坏的,最坏的情况是屎一样的代码配屎一样的注释。
    TomPig0216
    TomPig0216
    May 31, 2022
    145
    感觉我以前写的注释好像都是废话
    看了老哥们说的才发现好像很有道理
    注释是写为什么,而不是写是什么
    misaka20
    misaka20
    May 31, 2022
    146
    没那个高水平,就老老实实写注释吧,没错的
    Yest192
    Yest192
    May 31, 2022
    147
    @ryougifujino 没记错的话,我记得 clean code 还有两个建议也挺好的,1 是 方法尽量分得细一点,最好一个方法只做一件事,这样一方面可以复用,另一方面,如果是一个比较复杂的逻辑可以通过调用好几个方法来实现,这样整个大概逻辑就一目了然。 这也引出了第二个建议 就是方法名尽量写具体,比如用 getMonthIndexOfYear 而不是 getMonth 这种笼统的(随便举的例子,意会一下) 。
    我这几年写下来感觉这两个建议挺好,除非特别需要注意的坑点 一般自己 coding 不怎么需要写注释。
    soloHm
    soloHm
    May 31, 2022
    148
    api 功能比较单一,做这个事就是做这个事基本不会变,所以可以写清楚注释,但是在实际业务中,需求是会改变的,如果每次改变都去写一堆注释,反而增加了工作量。
    janda
    janda
    May 31, 2022
    149
    接手一个新项目、我觉得业务注释更重要了,要不然不结合这业务、我都不知道这这串代码的意思
    feirisu
    feirisu
    May 31, 2022❤️1
    150
    有人告诉你好的代码是最好的注释,那这个人一定是个骗子
    jazzg62
    jazzg62
    Jun 1, 2022
    151
    @brader 啊,注释里有毒,(⊙﹏⊙)
    edimetia3d
    edimetia3d
    Jun 1, 2022
    152
    只看局部,或者项目比较小的时候,代码 tell it self 显然是一个易于维护的选项, 我实现过的一些库,文档就很一句话" Read the code is much easier than read me."

    不过另一方面, 我接触过的项目大都是 infra, 而且基本算是大型的 infra, 比如 llvm 这种. 情况就变得复杂的多了

    这些项目里经常会有以下感叹:
    1. 这个注释 /文档说的真到位, 我终于明白为什么这里要这么设计了 /这个该怎么用了 /这个的工作原理了.
    2. 这个代码的行为和注释说的不一样啊, 我得提个 issue 问一下, 看看是实现错误还是文档错误.
    3. 我 F,这个 class 1000 行代码,连个 summary 都没有吗, 这不得把我脑壳看爆.

    这种场景中,我会说"充分且 updated 的文档"对这种大型项目绝对是一个必要项.
    kice
    kice
    Jun 3, 2022 via Android
    153
    如果只讨论函数内部的注释,先搞清楚代码会给谁看:

    *以下前提是有良好命名规则和不太高的代码复杂度*

    先把代码的排版弄好:大括号换行不换行统一,等号参数对齐,缩进都整理好,代码间加入合适的空行,变量声明位置和顺序什么的

    如果是给领导开会讲读,注释把执行顺序和逻辑介绍清楚。

    如果是给同组同事或者自己看,那么一些经常被问、奇怪反直觉的点写清楚就行。

    如果是写给其他同事,或者是当作库类放出去,函数内部注释就不是特别要紧,不过着重弄清楚错误 /异常处理相关是不会错。看库代码很多都是为了搞清楚 edge cases 。

    如果是写给新手,那么基本上就要每行都注释。

    如果是算法的代码,告诉是什么算法和有什么效果即可,网上有很多能很好解释算法的文章。

    代码写得差应该是学习怎么写代码,而不是说注释写清楚就行;注释能方便理解屎山,但是屎山不会因为好的注释变成好代码。
    v1v
    v1v
    Jun 3, 2022
    154
    写注释是个技术活,是否需要写?写啥?

    可以试着隔一段时间后看自己的代码,如果能很快就看出这段代码:
    - why:功能作用、返回值含义(调用者使用文档)
    - how:为啥这么写、怎么实现的(内部细节)

    就不用写,反之还是解释一下比较好
    v1v
    v1v
    Jun 3, 2022
    155
    @WOLFRAZOR #144 (还得加上不是同一种屎😏
    1  2  
    ❮ ❯
    About   ·   Help   ·   Advertise   ·   Blog   ·   API   ·   FAQ   ·   Privacy   ·   Solana   ·   951 Online   Highest 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 173ms · UTC 20:39 · PVG 04:39 · LAX 12:39 · JFK 15:39
    ♥ Do have faith in what you're doing.