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

[nuanshen]

[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 （还得加上不是同一种屎😏