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

[darknoll]

代码即注释

[yaphets666]

@dqzcwxb 人家啥工期，咱啥工期啊，差不多得了

[MatrixLau]

@brader #11 太坏了 哈哈哈哈哈

[demonps]

代码就是我我们交流的语言，除非异常复杂的逻辑，否则从不写注释

[fgwmlhdkkkw]

@SimonOne #89 这是什么语言呀？

[nuanshen]

@snoopyhai 领导在开会走读代码的时候提的呗，他的意思似乎是想让我们把代码翻译成中文写在注释里

[Abbeyok]

我觉得没错啊，自从用上了 copilot 之后，我就养成了写注释的习惯

[Leviathann]

声明式的代码才有代码即注释一说
全是命令式的代码一眼看过去鬼知道在干嘛，全是噪音

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

这也是现代编程语言的一个进步的方向

[nuanshen]

@skys215 我也是这种想法

[sky857412]

后端业务这么复杂，再好的代码也需要注释，今天 A1 需求，明天 A2 需求，这没有注释都看不懂

[nuanshen]

@Building 嗯，认同

[asdjfuhgasiduf]

让我想起本科时候上的软件工程课了，代码的可读性比代码的运行效率优先级更高。

[dbow]

跟注释关系不大， 容易写测试的代码，就是好代码

[BestP]

没有注释又能一眼读懂的代码才是好代码

[xuyang2]

@Seayon
10 也是拍脑袋，8 也是拍脑袋，
五十步笑一百步了属于是

[ukyoo]

可别吹了, 有几个能把代码写的"自解释"的, 业务代码都是很复杂的, 写注释能帮别人快速理解

[7gugu]

业务逻辑都要写注释，平时根本抽象不了多少代码，很多注释都是为了某次莫名的修改而增加的，不然前人离职了，代码就动不了了。

[lance1ot]

实在不能苟同楼上几位“高手代码就是自注释”的观点。曾读过 MSRA 大佬的代码，觉得很头疼。我觉得不要求注释写得非常详细，只要能概述一下代码块的功能就好，说明输入输出之类的，让人知道是干什么的之后再去理解会容易很多。
就像你读书前会看书名，而不是根据书的内容去倒推书名

[SimonOne]

@fgwmlhdkkkw #105 abap

[Seayon]

@xuyang2 1. 的确是拍脑袋，总比不拍好。2. 没看懂

[Seayon]

@qingshuang 感谢指导，这样好像是可以的，不过已经有 10 个索引了太多了 😂。

[cp19890714]

任何话术道理都有其对应的场景，不是万能的。

[6167]

我因为注释太多，被挂了机试

[B1ankCat]

矫枉必须过正，不过正不能矫枉

[YYYeung]

注释（这里不算方法签名上的那部分）应该是写某个模块的总体思路；或某个有惊喜的地方需要稍作注明，用于提示别人或以后的自己
而本来写在具体实现中的注释，应该通过好的变量名和方法名来体现；如果觉得其中的逻辑过于复杂，想写注释时，应该先思考一下逻辑是否可以进一步拆分

[PureWhiteWu]

别总把自己当高手，当牛逼的人，以为自己代码写得很漂亮，能自注释。
不信你试试回过头去看半年前你写的代码。

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

所以，多写点注释吧，把上下文说清楚，这不是留给后来人的，其实是帮助未来的你。
不写注释的研发，一看就知道没有过大型团队协作项目的经验。

[drackzy]

注释写的好，老板招个实习生，学会了你就被替代了。

[pengtdyd]

注释是写给高手看的，不是写给菜鸡看的，菜鸡就算你写了，他依旧不明白

[lldld]

@Seayon 你的需求为什么不用 payTime, id 两个来排序?

[godloveplay]

@brader #11 呃呃呃，诸如 注释撒谎 变量名撒谎 表名撒谎 扩展字段偷偷使用不加注释 太多太多了。

[tairan2006]

大部分情况下，这句说法是对的

其实注释最重要的是和代码保持一致，很多人更新了代码但是不更新注释

[godloveplay]

业务逻辑 /流程 注释 很重要

代码执行操作 很轻松能看明白的 不建议 注释

[DiamondY]

估计觉得这句话没问题的，都没看过流水账日记那样的代码注释吧？

[54yinhang]

过犹不及

[yxzblue]

谁说的？谁说的？

[Seayon]

@lldld 谢谢谢谢，我们考虑下加这个索引。前人这个做的，我想他考虑的是可能现有索引已经太多了（ 10 个）所以不想加索引。

[getinlight]

只要是给时间，注释我都能写成作文。就怕既要又要还要。。。

[cominghome]

这句话后面代表的意思是对的，即，好的代码是要让人能看懂的，只盯着这句话就会显得太绝对

[nuanshen]

@getinlight 做业务的敏捷开发，实在没多少时间，业务还多变

[w0017]

代码写得结构清晰点，多迭代两次，尽量少用语法糖

[abolast]

注释写到自己的笔记本上

[l00t]

不要把注释当文档。注释取代不了文档。该写需求文档方案设计文档的时候还是得写，别以为可以放到注释里。

[macha]

注释多讲讲 why 。
how 的话，好的代码确实是自解释的。但是 why 确实很难做到自解释。

[WOLFRAZOR]

屎一样的代码没注释不是最坏的，最坏的情况是屎一样的代码配屎一样的注释。

[TomPig0216]

感觉我以前写的注释好像都是废话
看了老哥们说的才发现好像很有道理
注释是写为什么，而不是写是什么

[misaka20]

没那个高水平，就老老实实写注释吧，没错的

[Yest192]

@ryougifujino 没记错的话，我记得 clean code 还有两个建议也挺好的，1 是 方法尽量分得细一点，最好一个方法只做一件事，这样一方面可以复用，另一方面，如果是一个比较复杂的逻辑可以通过调用好几个方法来实现，这样整个大概逻辑就一目了然。 这也引出了第二个建议 就是方法名尽量写具体，比如用 getMonthIndexOfYear 而不是 getMonth 这种笼统的(随便举的例子，意会一下) 。
我这几年写下来感觉这两个建议挺好，除非特别需要注意的坑点 一般自己 coding 不怎么需要写注释。

[soloHm]

api 功能比较单一，做这个事就是做这个事基本不会变，所以可以写清楚注释，但是在实际业务中，需求是会改变的，如果每次改变都去写一堆注释，反而增加了工作量。

[janda]

接手一个新项目、我觉得业务注释更重要了，要不然不结合这业务、我都不知道这这串代码的意思

[feirisu]

有人告诉你好的代码是最好的注释，那这个人一定是个骗子

[jazzg62]

@brader 啊，注释里有毒，(⊙﹏⊙)

[edimetia3d]

只看局部,或者项目比较小的时候,代码 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]

如果只讨论函数内部的注释，先搞清楚代码会给谁看：

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

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

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

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

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

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

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

代码写得差应该是学习怎么写代码，而不是说注释写清楚就行；注释能方便理解屎山，但是屎山不会因为好的注释变成好代码。

[v1v]

写注释是个技术活，是否需要写？写啥？

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

就不用写，反之还是解释一下比较好

[v1v]

@WOLFRAZOR #144 （还得加上不是同一种屎😏