究竟要不要写代码注释?

Posted viaiu

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了究竟要不要写代码注释?相关的知识,希望对你有一定的参考价值。

技术分享图片

看完上图你是什么反应?会骂人吗?会就对了……,代码整洁之道,是一条很漫长的路,注释是其中一部分。

如果是一个很大的方法,要不要加注释?一个大方法按照它的功能被分割成几个小方法,这样代码就比较容易阅读了,但有的童鞋说能在项目的deadline里面搞出来就行了,哪有时间整理这种大方法?为了让你的搭档或者接手者,更轻松的理解,让她/他少加班,抽时间还是整理一下吧。按照树的结构,一个主干,其他分支都是处理不同的逻辑。

如果是小方法能做到见名知意,就一定要见名知意,习惯总是要培养的,接一句鸡汤:走得慢并不要紧,只要你坚持不停地走,那么总有一天你能走到你想要到达的地方,能超过道旁那些不敢走的人。走正道!

大牛们总是说:代码就是最好的注释。可惜我还没有达到那个程度。但是我依然尝试着用命名代替注释,发现自己做的并不对,如果你团队的新人呢?比较复杂的方法,靠命名?所以这个时候还是建议把注释写的清清楚楚,其一:为了自己以后维护的方便; 其二:为了其他人接手的方便。

总结一下:

  • 如果自己的英语不好

对我们来说第一语言是中文的,英语不好情况就不一样了,这就是为什么国人的建议大多要求注释详尽,让代码更易读易懂;而老外的建议几乎是尽可能的少;符合我国基本国情。

  • 如果自己的水平还不够

对于很复杂的逻辑,务必用12345的顺序依次写清楚;对于函数中的某个参数,需要解释为什么要设置这个参数,尤其是公用工具类里面的函数---说清楚参数的背景含义,可以让其他调用者理解的更加清晰。

  • 如果整个团队水平参差不齐

一般不要用英文写。虽然这样看起来格调很低,但胜在大家都能轻松的看懂。写代码不能太傲娇,不能太任性,写注释也不要太傲娇,目的是让你的搭档或者接手者,更轻松的理解,提高效率,早点回家老婆孩子热炕头。

我们不能保证每个团队里面的每个成员都是大神,写该写的注释,单一定要去尝试用方法名和变量名去替代注释,说不定哪一天你也成为了大神?

技术分享图片

稍后等于永不,行动起来……

以上是关于究竟要不要写代码注释?的主要内容,如果未能解决你的问题,请参考以下文章

Team Leader 究竟要不要写代码?

Team Leader 究竟要不要写代码?

Team Leader 究竟要不要写代码?

代码要写注释吗?写你就输了

代码要写注释吗?写你就输了

代码要写注释吗?写你就输了