注释的艺术

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/riddle1981/article/details/77203573

代码注释也是一种艺术,如果不注释代码的阅读者会很难理解编写者的意图,也可能一段时间后自己也看不懂自己写的是什么。代码不仅需要写也需要时常维护。过段时间后需要对注释进行修改,没必要的也应当进行删除。
而通常的注释规范应当如下:
1、 修改代码时,总是使代码的注释保持最新, 为了防止问题反复出现,对错误修复和解决方法代码必须使用注释。

2、 在每个函数、方法的开始,应该提供标准的注释以指示例程的用途,注释样本应该是解释它为什么存在和可以做什么的简短介绍。

3、 避免在代码行的末尾添加注释;行尾注释使代码更难阅读。

4、 在变量声明时,应在行尾添加注释;在这种情况下,将所有行尾注释应使用公共制表符(Tab)在一处对齐。

5、 避免杂乱的注释,如一整行星号。而是应该使用空白将注释同代码分开。

6、 在编写注释时使用通俗易懂的句子。注释应该阐明代码,而不应该增加多义性。

7、 对由循环和逻辑分支组成的代码使用注释。这些可以帮助源代码读者理解代码书写目的。

8、 在所有的代码修改处加上修改标识的注释,创建标识和修改标识由创建或修改人员的姓名加日期组成,如:磊20081216

9、 为了是层次清晰,在闭合的右花括号后注释该闭合所对应的起点。

10、在部署发布之前,移除所有临时或无关的注释,以避免在日后的维护工作中产生混乱。

使用以下几种说明性注释会使代码注释更加一目了然。
TODO: + 说明:
如果代码中有该标识,说明在标识处有功能代码待编写,待实现的功能在说明中会简略说明。

FIXME: + 说明:
如果代码中有该标识,说明标识处代码需要修正,甚至代码是错误的,不能工作,需要修复,如何修正会在说明中简略说明。

XXX: + 说明:
如果代码中有该标识,说明标识处代码虽然实现了功能,但是实现的方法有待商榷,希望将来能改进,要改进的地方会在说明中简略说明。

猜你喜欢

转载自blog.csdn.net/riddle1981/article/details/77203573