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

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

  •  
  •   nuanshen · 2022-05-30 09:45:29 +08:00 · 13459 次点击
    这是一个创建于 669 天前的主题,其中的信息可能已经有所发展或是发生改变。
    155 条回复    2022-06-03 15:44:35 +08:00
    1  2  
    darknoll
        101
    darknoll  
       2022-05-30 17:16:39 +08:00
    代码即注释
    yaphets666
        102
    yaphets666  
       2022-05-30 17:18:57 +08:00
    @dqzcwxb 人家啥工期,咱啥工期啊,差不多得了
    MatrixLau
        103
    MatrixLau  
       2022-05-30 17:24:31 +08:00 via iPhone
    @brader #11 太坏了 哈哈哈哈哈
    demonps
        104
    demonps  
       2022-05-30 17:28:30 +08:00
    代码就是我我们交流的语言,除非异常复杂的逻辑,否则从不写注释
    fgwmlhdkkkw
        105
    fgwmlhdkkkw  
       2022-05-30 17:28:32 +08:00
    @SimonOne #89 这是什么语言呀?
    nuanshen
        106
    nuanshen  
    OP
       2022-05-30 17:36:03 +08:00
    @snoopyhai 领导在开会走读代码的时候提的呗,他的意思似乎是想让我们把代码翻译成中文写在注释里
    Abbeyok
        107
    Abbeyok  
       2022-05-30 17:37:57 +08:00
    我觉得没错啊,自从用上了 copilot 之后,我就养成了写注释的习惯
    Leviathann
        108
    Leviathann  
       2022-05-30 17:39:16 +08:00
    声明式的代码才有代码即注释一说
    全是命令式的代码一眼看过去鬼知道在干嘛,全是噪音

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

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

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

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

    其实注释最重要的是和代码保持一致,很多人更新了代码但是不更新注释
    godloveplay
        132
    godloveplay  
       2022-05-31 08:50:31 +08:00
    业务逻辑 /流程 注释 很重要

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

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

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

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

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

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

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

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

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

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

    就不用写,反之还是解释一下比较好
    v1v
        155
    v1v  
       2022-06-03 15:44:35 +08:00
    @WOLFRAZOR #144 (还得加上不是同一种屎😏
    1  2  
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5400 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 36ms · UTC 08:58 · PVG 16:58 · LAX 01:58 · JFK 04:58
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.