多语言展示
当前在线:399今日阅读:60今日分享:41

程序注释应遵守的原则

程序的注释有助于代码的理解,是程序员之间进行交流的有效途径,合理的注释有利于日后的软件维护。    下面介绍一些注释应该遵守的基本原则:
工具/原料

程序代码

方法/步骤
1

1.一般情况下,源程序中有效注释量必须在20%以上,且注释应该准确,易懂,防止注释二义性。注释应当与其描述的代码相邻,可放在代码的上方或者右方,不可放在下方,且要将注释与其上方的代码用空行隔开。

2

2.变量注释应该放在变量定义之后,并说明变量的用途和取值约定。文件的头部必须进行注释,包括.h文件、.c文件、.cpp文件等。注释要列出版权说明、文件名称、版本号、生成日期、作者、内容提要、功能以及与其他文件的关系、修改日志等。

3

3.在函数的头部注释要列出函数的名称、功能、输入\输出参数,返回值与修改信息等等。在用{  }包含的代码块的结束处应该加以注释。特别是有多重嵌套的时候。应在代码的功能、意图层次上进行注释,要提供有用的、额外的信息。

4

4.如果数据结构声明(包含数组、结构、类等)不能充分注释的,必须加以注释。对数据结构的注释应该放在其上方相邻的位置,对结构中每个域(成员)的注释应放在此域的右方。全部变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等进行说明。

5

5.对于switch语句下的case语句,如果因为特殊情况需要处理完一个case语句后进入另一个case语句进行处理,则必须在该case语句处理完、进入下一个case语句前加上明确的注释。这样能有效防止遗漏break语句,也能使维护人员清晰的了解程序的流程。

注意事项

注释可分为序言性注释和功能性注释两大类。

推荐信息