当前位置:C++技术网 > 资讯 > 编程规范实践总结-注释篇

编程规范实践总结-注释篇

更新时间:2015-06-24 16:15:02浏览次数:1+次

意义:

    可以极大提高程序稳定性,提高程序可维护性,提高程序快速维护效率,降低维护成本。有清晰的注释,可以快速定位代码,调试,也可以避免记忆错乱导致逻辑出错。好的注释,可以降低后期增加功能带来新问题的几率。

0.注释原则:简洁 清晰 逻辑

简洁表示注释不要太长,占篇幅,视觉不好
清晰是要使用合适的方式注释,配合排版,保持整齐美观
逻辑表示注释中可以快速看清逻辑,使用自己熟悉的语言写注释


1.固定的注释风格,可以使自己永远清晰注释所解释的代码。
注释一时解释下面的代码,一时解释上面的代码,一时解释左侧的一行代码,一时解释下面的所有代码,从而容易造成混淆,导致程序逻辑不能从注释中轻易看出。只要确定一个即可。
我的注释风格:
代码前:/* - 此条注释是解释以下的代码,到一下条注释为止 - */
代码右侧:// - 此条注释只解释左侧的一行代码
函数整体


2.注释要看得到逻辑流程,而不是具体的一句代码的意思
一段代码,是一段程序逻辑,但是几行代码完成一个逻辑步骤,这种只需要一个功能逻辑注释即可。要做到,只看注释就能看懂程序逻辑。


3.关键性语句,非标准语句,自定义函数,条件转移语句加注释
这些是程序逻辑的容易产生分歧的语句,特别是条件转移,每一个转移都要注释,每一个转移要注明转移原因,转移到哪去,为什么,简要说明。


4.对于状态码,不仅要标注每一个状态是什么,还要注明作用
有些函数的返回码是状态,真或者假,或者整型码,不仅要标注是什么码,还要标注作用,推荐使用列表形式注释,简洁、一目了然。


5.代码更改,注明为什么更改,改了什么关键,或者重构什么
注明更改,可以有助于恢复原先代码逻辑,可以预防改错后恢复。


6.每个文件前标注编码者,编码时间,修改者,修改了什么,修改时间。
在完成编码或者修改编码后,需要更新文件头的注释,以备后续查找问题找到根据,直接看文件头即可知道文件做过什么改动,对于代码量大的文件的改动更是需要如此。只需要简要注释。


7.所有变量要表明使用的范围,作用
局部变量,临时变量,全局变量都需要标注使用范围和作用,可以降低后勤改代码引起牵连错误关系,修改一处代码却引来更多的地方的错误。单功能体尽量使用局部变量。


8.需要注意的关键信息加以说明
对于有些变量只能取什么,什么类型,取值范围要加以说明指定,以便调试时观测变量的值确定是否出错,而不用记忆。常量的值尽量使用宏,可以是全局宏,也可以是局部宏。


9.函数的整体功能和返回值说明
    在头文件中标注函数功能和返回值说明,在实现中也简要说明,提高代码阅读效率,避免反复切换到头文件看说明。注释以单行写在函数名右侧,复制函数时会一同将注释复制走,如果放在前面可能就漏掉了。或者在函数内部开头,用一个特别的注释风格,将函数功能,返回值,等说明。头文件的可以简单描述,cpp文件需要详细描述。在cpp文件中多加一个注释并不多余,还是提高代码定位和维护效率。

    后期实践不断的完善平时遇见的不规范导致的问题,并规范代码写法,并更新到自己的编程规范中。如果你有好的经常遇见的问题,因为不规范导致的错误,请相互交流,促使写出自己定制的规范代码,降低软件错误率,提高软件稳定性和可维护性。欢迎提出建议。