软件编写规范(注释篇)
来源:互联网 发布:淘宝面膜便宜的原因 编辑:程序博客网 时间:2024/06/10 10:07
//摘抄自华为软件编写规范
1、:一般情况下,源程序有效注释量必须在 20 %以上
说明:注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语
言必须准确、易懂、简洁。
2、说明性文件(如头文件.h 文件、.inc 文件、.def 文件、编译说明文件.cfg 等)头部应进行注释,
注释必须列出:版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明
Copyright (C), 1988-1999, Huawei Tech. Co., Ltd. File name: // 文件名 Author: Version: Date: // 作者、版本及完成日期 Description: // 用于详细说明此程序文件完成的主要功能,与其他模块 // 或函数的接口,输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表,每条记录应包括函数名及功能简要说明 1. .... History: // 修改历史记录列表,每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. ...
3、¹2-3:源文件头部应进行注释,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。
Copyright (C), 1988-1999, Huawei Tech. Co., Ltd. FileName: test.cpp Author: Version : Date: Description: // 模块描述 Version: // 版本信息 Function List: // 主要函数及其功能 1. ------- History: // 历史修改记录 <author> <time> <version > <desc> David 96/10/12 1.0 build this moudle
说明:Description 一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。History是修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述。
4、函数头部应进行注释,列出:函数的目的/ 功能、输入参数、输出参数、返回值、调用关系(函数、表)等
Function: // 函数名称 Description: // 函数功能、性能等的描述 Calls: // 被本函数调用的函数清单 Called By: // 调用本函数的函数清单 Table Accessed: // 被访问的表(此项仅对于牵扯到数据库操作的程序) Table Updated: // 被修改的表(此项仅对于牵扯到数据库操作的程序) Input: // 输入参数说明,包括每个参数的作 // 用、取值说明及参数间关系。 Output: // 对输出参数的说明。 Return: // 函数返回值的说明 Others: // 其它说明
5、注释的内容要清楚、明了,含义准确,防止注释二义性
6、避免在注释中使用缩写,特别是非常用缩写
说明:在使用缩写时或之前,应对缩写进行必要的说明。
7、注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开
8、于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时都必须加以注释
/* active statistic task number */ #define MAX_ACT_TASK_NUMBER 1000 #define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */ 这里写代码片
9、数据结构声明( 包括数组、结构、类、枚举等) ,如果其命名不是充分自注释的,必须加以注释。
对数据结构的注释应放在其上方相邻位置,不可放在下面;对结构中的每个域的注释放在此域的右方
10、全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明
11、注释与所描述内容进行同样的缩排
12、将注释与其上面的代码用空行隔开
13、对变量的定义和分支语句(条件分支、循环语句等)必须编写注释
14、对于 switch 语句下的 case 语句,如果因为特殊情况需要处理完一个 case 后进入下一个 case 处理,必须在该 case 语句处理完、下一个 case 语句前加上明确的注释
说明:这样比较清楚程序编写者的意图,有效防止无故遗漏 break 语句。
15、避免在一行代码或表达式的中间插入注释
16、在代码的功能、意图层次上进行注释,提供有用、额外的信息
说明:注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
示例:如下注释意义不大。 /* if receive_flag is TRUE */ if (receive_flag) 而如下的注释则给出了额外有用的信息。 /* if mtp receive a message from links */ if (receive_flag)
17、注释应考虑程序易读及外观排版的因素,使用的语言若是中、英兼有的,建议多使用中文,除非能用非常流利准确的英文表达
- 软件编写规范(注释篇)
- 软件编写规范(排版篇)
- 软件编写规范(程序效率篇)
- 软件编写规范(质量保证篇)
- 软件编写规范(可读性)
- Java 编写注释规范模板
- 软件程序编写规范 - 上(仅供参考)
- 软件程序编写规范 - 中(仅供参考)
- 软件程序编写规范 - 下(仅供参考)
- 软件编写规范(标识符命名)
- 项目软件编写规范
- 软件开发文档编写规范
- 软件开发文档编写规范
- C语言编写规范之注释
- 软件编程规范总则-2 注释
- 华为软件编程规范学习(二)--注释
- 华为软件编程规范学习(二)--注释
- 关于软件编写的规范测试
- jquery实现拖动
- Android 常用设计模式之 -- 策略模式
- HDU5969(二进制计算)
- gitlab CI
- 逻辑回归中代价函数求导推导
- 软件编写规范(注释篇)
- jsp
- Lab_2
- nvm的window下配置和安装
- tcp粘包和nagle算法
- Caffe-SSD(single-shot-multibox)在Windows平台下的配置(CPU和GPU)与训练记录
- gmapping 算法解析
- void Delay(__IO u32 nCount)最简单的延时函数
- NOIP2004 虫食算 题解