写代码注释的注意事项

首先要明白,好注释并不是用于重复代码,或是解释代码(你会这门编程语言就能读懂,为什么还要通用语言解释呢。如果代码过于复杂,应该加以重构,而不是花费大力气去解释它)。

而是以一种高层抽象解释你的意图是什么(好比解释你的业务要做什么)。

当然,坏注释会产生反效果,如无关的注释和错误的注释等。

有三种注释是值得建议的:

  1. 概述性注释:将若干行的代码的意思以一两句话说出来,便于他人阅读你的代码。
  2. 目的性注释:指明代码的意图,告诉人家你要解决什么问题(但无需说明怎么解决)。
  3. 代码无法表述的注释:某些信息不能用代码表达,又必须出现在源代码中。其实这个我们挺熟悉的,例如对类的版权声明,版本号,以及时间等。

记住,注释无需太多,太多的注释可能会带来反效果。我曾有段时间,几乎想在每一句代码上加注释。后来再看回来,其实很多都是解释代码注释。即使没有这样的注释,别人也能轻易读懂我的代码。那这样的注释就是不该出现的。

还有一点就是先写注释再写代码比先写代码在写注释要好。正如前面所说,注释属于高层概述。当你明白了做什么,你的代码就会水到渠成一些。

避免使用行尾注释,但有两个例外:

  1. 行尾注释用于数据声明。(如temp是干什么用的)
  2. 用行尾注释标注块尾。(当代码块很长,你就知道这种行尾注释的重要性了)

不要注释投机取巧的代码,应该要重写它。(不要不舍得写过的那些投机取巧的代码,因为可能会给别人带来阅读糟糕注释的体验)

至于最佳注释量,IBM研究发现,每十条代码语句有一条注释,在这样的密度下,程序的清晰度最高。其实这个并不重要,重要的是你的注释有它的价值。

总之,注释真的很重要,前提是你写的是好注释。

评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值