代码里注释写太多，会挨打吗？

第一时间关注土叔的趣文

前几天，有个同行朋友在我的微信上留言，问我项目代码里注释写太多会挨打吗？顺手还给我甩了一张截图，上面密密麻麻的全是手工注释。

看完之后，我跟她说，挺好的，我已经备好手枪了。

当时我记得跟她开了句玩笑话。玩笑归玩笑，接下来，马上进入正题。

「 如何把握这个尺度 」

代码里写注释，如何才叫多，什么是多，什么是少，如何才能把握这个尺度？

还记得老前辈的话犹在耳畔，一份经久不衰的代码，注释量与代码量的比例应该至少为 2:1。

我很严肃地跟她说，写多了我不知道，写少了真的可能会被同事枪杀。

从关爱生命的角度出发，土叔送你四个大字：适可而止。

关键是要注意一个度。挨打与否，就在一念之间。

说真的，我要是接手一个项目注释这么详细，我会请那个人吃顿饭，而且这个注释好在是在代码块外，如果是代码中，注释比代码还多，影响阅读代码那体验就很糟了。

因此得出一个结论：注释写在代码块之外，恭喜你，你暂时是安全的。如果是写在代码块内，也要恭喜你，赶紧来我这儿喜提拳击手套一副。

不过也有在代码里玩出花样的。我司之前有个同事，写的注释特别有意思，注释里面带了很多段子，有时候找 BUG 找的心烦，看到他的诡异注释还是挺不错的。

「 写注释的三个层次 」

写注释，有三个层次，土叔总结如下:

1. 什么代码都不写注释

2. 什么代码都写注释

3. 只在关键处(难理解处 /易出错处 /易混淆处)写注释

前同事也喜欢写很多注释, 还要求我也跟他一样写,200 行的代码, 500 行的注释, 而且注释跟代码还不一样.

注释里参数是字符串类型, 代码里却是布尔类型.

所以，此处为什么是前同事？因为代码不规范，老板给他放长假了。

「 周围同事怎么看 」

对于这个问题，我还特意问了下我司的后端大佬，他回复我，其他语言我不好说，反正在java里，如果在方法里面写注释，不单独拿出一行写，我绝对会nen死他，哈哈哈哈。

我怕误导那位朋友，所以又咨询了我司的前端同事，他跟我说，喜欢这样的人，除了特别牛的大佬，应该都不会觉得注释多。唯一比较尴尬的情况是，注释和代码版本不同步，代码是新代码注释是旧代码的注释，注释就没什么卵用了。

既然前端和后端的小哥哥们都问过了，那就顺便再张嘴问下我司的技术负责人吧，听听leader是怎么说的。

我们leader看完截图后回复我，这个注释写得挺好。把参数来意、方法逻辑在规范的地方写上了，特别有助于团队开发。如果是写过多注释在方法体内就变成除臭剂了，这样就不太好了，代码阅读起来费劲。不过这一切都是团队一起规范起来才行，方法体有变更就要即时更新注释，特别是有些家伙改了你的东西没有即时更新，那就TM操蛋了，哈哈。

「 写注释究竟是为了什么 」

寻其根本，写注释是为了什么？

对于这个问题，我的答案是：能让大多数人轻松看懂我的代码，简而言之就是提高可读性。

而提高可读性不一定就要靠尽可能多地写注释，甚至不一定要靠注释，不管你用什么办法，只要达到了“能让大多数人轻松看懂我的代码”的目标就可以了。

注释越多就越能越轻易看懂吗？

不一定，像《三傻大闹宝莱坞》里主角用了一大串“定义”来描述“书”的时候，教授完全没听懂是什么。

但有的时候算法真的非常复杂，少一点注释就解释不清楚，这时候不妨吧代码拆一拆，分段由浅及深写注释，可能效果会更好一些，想象一下如何才能给一个对物理学完全不了解的小学生讲明白相对论。

当然了，群里如果有所谓的技术大佬跟你吹嘘，真正好的代码是不需要注释的，如果你需要大量注释来解释你的代码，那说明你的代码还是不够好。

请记住，这是一句装逼话，群里吹水你也信，你看看Vue.js源码里有多少注释（杠精不要跑过来跟我说，/* 英文的注释不算 */

）。

Are you sure ?

「 好奇心害死猫 」

文末彩蛋：聊天行将结束之际，那位问我问题的朋友，跟我说，让土叔见笑了。这幅图的出处是我写的代码。我不但有写注释的习惯，还有写文档的怪癖。除了这个注释，我还配了一个上万字的文档..........

我顿时惊为天人。