代码里注释写太多,会挨打吗?

第一时间关注土叔的趣文

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

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

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

「 如何把握这个尺度 」

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

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

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

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

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

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

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

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

「 写注释的三个层次 」

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

1. 什么代码都不写注释

2. 什么代码都写注释

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

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

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

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

「 周围同事怎么看 」

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

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

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

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

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

寻其根本,写注释是为了什么?

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

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

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

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

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

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

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

)。

Are you sure ?

「 好奇心害死猫 」

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

我顿时惊为天人。

原文发布于微信公众号 - 闰土小叔(running_hacker)

原文发表时间:2018-10-22

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏大数据文摘

深度解析12306数据泄露之谜

3052
来自专栏Web 开发

我也来刷到CM7.1

2011年10月10日,著名的的Android第三方ROM团队CyanogenMod发布了最新的稳定版CM7.1,同时提供大量机型的支持~

820
来自专栏智能大石头

MF前传——探索者二号简介

   因为探索者一号供不应求,远超预期,并且我们自己设计制造的成本太高,所以没有再次生产。而是选择较高性价比的第三方STM32开发板作为MF学习板,是为探索者二...

23610
来自专栏大数据挖掘DT机器学习

python爬虫+R数据可视化 实例

Python 和 r语言这对黄金搭档,在数据获取,分析和可视化展示方面,各具特色,相互配合,当之无愧成为数据分析领域的两把利剑。该项目分为两个模块: 1,数据准...

4834
来自专栏FreeBuf

WPA2 安全协议惊现高危漏洞,几乎涉及所有 WiFi 设备(附固件升级列表)

近日,鲁汶大学的研究人员 Mathy Vanhoef 在 WPA2 协议中发现了严重的安全漏洞,这对无线网络的安全造成了极大的考验。本文简要介绍了此次攻击的技术...

2449
来自专栏智能大石头

MF前传——探索者二号简介

    因为探索者一号供不应求,远超预期,并且我们自己设计制造的成本太高,所以没有再次生产。而是选择较高性价比的第三方STM32开发板作为MF学习板,是为探索者...

1000
来自专栏北京马哥教育

上班第一天,一个合格的运维应该做什么?

运维行业正在变革,推荐阅读:30万年薪Linux运维工程师成长魔法 作为一名运维工程师,如果你在春节放假期间没有被报警电话和邮件吵醒过,那说明你在放假前的准备...

4108
来自专栏沃趣科技

隔壁老王的数据备份“变形”记

隔壁老王作为一名合格的DBA 守护数据安全是他不可推卸的责任 比如每一次的数据库备份 可是你懂的 那备份的速度 ? 于是乎 兢兢业业的老王一边盯着屏幕 一边若有...

4237
来自专栏安恒信息

携程曝重大安全漏洞 客户信用卡信息或遭泄露

3月22日,乌云平台连续披露了两个携程网安全漏洞,漏洞发现者称由于携程开启了用户支付服务借口的调试功能,导致携程安全支付日志可被任意还可读取,日志...

2958
来自专栏机器人网

国外DIY牛人教你做Wifi机器人(最全教程)

一、前言 Wifi机器人(Wifi Robot):其实是一辆能通过互联网,或500米以外的笔记本无线设施来远程控制的遥控汽车。由于在车上配备了一个网络摄像...

3325

扫码关注云+社区

领取腾讯云代金券