软件编码和命名规范.docx
- 文档编号:14198327
- 上传时间:2023-06-21
- 格式:DOCX
- 页数:20
- 大小:423.81KB
软件编码和命名规范.docx
《软件编码和命名规范.docx》由会员分享,可在线阅读,更多相关《软件编码和命名规范.docx(20页珍藏版)》请在冰点文库上搜索。
软件编码和命名规范
XXXXXX项目
编码和命名规范
项目号
版本号
作成者
确认者
承认者
制定日
变更记录
版本
发布日
担当者
内容
1.概述
.目的
在XXXX项目架构设计开始之时,有必要成立起适合本项目的编码规范和命名规约,为顺利开展软件架构设计及随后的各阶段设计工作提供必要的基准和规范。
本编码规范是在《XX软件课编码规范》的基础上,按照本案的特点进行必要的补充和修正而制定完成的。
此编码规范是以C语言作为开发语言的前提下编写的,在项目的整个生命周期中,以此作为开发工作开展的基准。
.组成
XXXX项目编码规范主要由以下几个部份组成:
(1)版权声明。
(2)文件结构。
(3)命名规则。
(4)程序版式。
(5)语法规范。
(6)自动注释添加。
2.详述
1
2
.版权声明
版权声明位于头文件和概念文件的开头(参见示例1-1),主要内容有:
(1)版权信息
(2)文件名称,摘要
(3)日期,作者和修改内容
示例2-1版权声明
【规则2-1-1】修改内容要注明修改原因,比如Bug修正、式样变更和增加新功能等。
.文件结构
2.2.1.头文件结构
头文件由四部份内容组成:
(1)头文件开始处的版权声明(参见示例2-1)。
(2)预处置块。
(3)宏概念。
(4)函数和结构体的声明。
假设头文件名称为,头文件的结构参见示例2-2。
【规则2-2-1】为了避免头文件被重复引用,应当用预编译伪指令ifndef/define/endif结构产生预处置块。
假设头文件名称为,变成HEAD_H在头文件中的预编译伪指令中利用,参见示例2-1。
【规则2-2-2】用#include<>格式来引用标准库的头文件。
【规则2-2-3】用#include“”格式来引用非标准库的头文件。
示例2-2头文件的结构
2.2.2.概念文件的结构
概念文件有四部份内容:
(1)概念文件开头处的版权声明(参见示例2-1)。
(2)对头文件的引用。
(3)宏概念、函数的引用声明及变量概念。
(4)程序的实现体。
概念文件的结构参见示例2-3。
示例2-3概念文件的结构
3.命名规则
共性规则
命名的两个大体原则:
(1)含义清楚,不易混淆。
(2)不和其它模块、系统API的命名相冲突。
【规则3-1-1】标识符应当直观且能够拼读,可望文知意。
标识符应采用英文单词或其组合,便于记忆和阅读。
切忌利用汉语拼音来命名。
程序中的英文单词不该太复杂,用词应当准确。
【规则3-1-2】标识符的长度应当符合“min-length&&max-information”原则。
例如:
变量名MaxVal就比MaxValueUntilOverflow,简练易懂。
【规则3-1-3】程序中不要出现仅靠大小写区分的相似的标识符。
例如:
intx,X;/*变量x与X容易混淆*/
voidfoo(intx);/*函数foo与FOO容易混淆*/
voidFOO(floatx);
【规则3-1-4】程序中不要出现标识符完全相同的局部变量和全局变量,虽然二者的作用域不同,而不会发生语法错误,但会令人误解。
【规则3-1-5】变量命名,变量的名字应当利用“名词”或“形容词+名词”。
每一个单词的首字母大写。
要加上前缀或后缀作为类型或属性的标识。
对于无符号变量要加上u和位数。
例如:
UINT16u16MaxVal;
对于有符号变量要加上s和位数。
例如:
INT16s16MaxVal;
对于单指针,前面加上p,对于双指针要加上pp,而且还要加上指针类型的标识。
例如:
UINT*puCtrl;
VOID*pvFunc;
UINT*ppuTableID;
对于char型变量前面要加上c;对于bool型变量前面加上b。
对于double或float型变量,前面加上f。
例如:
CHARcTimeout[50];
BOOLbResult;
DOUBLEfMinVal;
对于全局变量要加上g_。
例如:
UINTg_uStatusRecord;
对于结构体,要采用typedef将结构体从头命名,名称要采用英文全拼,尽可能详尽的表述出该结构体的含义。
例如:
typedefstruct
{
UINT16u16Year;
UINT8u8Month;
UINT8u8Day;
UINT8u8Hour;
UINT8u8Min;
UINT8u8Sec;
UINT8u8Week;
}COMMON_SYSTEM_TIME;
对于列举的概念,与结构体的概念方式相同。
在概念列举名称时加上后缀_e,在概念列举变量时加上前缀e。
例如:
typedefenum
{
SC_MEDIA_TV=0x01,
SC_MEDIA_AUDIO=0x02,
SC_MEDIA_DATA=0x03
}SC_MEDIA_TYPE;
【规则3-1-6】函数命名:
函数命名具体规则是:
主模块+子模块+函数名
主模块名称由4个字母缩写而成,例如:
SYMG、AVEX等。
子模块名称也是由4个字母缩写而成,例如:
UIOD、UIPR等。
函数名应当利用“动词”或“动词+名词”(动宾词组)。
函数名要表达出函数的作用,尽可能利用单词全拼。
各单词利用起始的大写字母分隔,对于较长的单词可采用缩写(见表3-1标准字典)。
【规则3-1-7】文件命名
文件命名要表现该文件所属模块及其实现的功能
具体为:
模块名+实现功能
【规则3-1-8】常量命名:
常量全用大写的字母,用下划线分割单词。
例如:
constintMAX_LENGTH=100;
【规则3-1-9】宏概念全数采用大写,单词之间用”_”连接(一般不超过4个单词)。
例如:
#defineDELAY_TIME20
【规则3-1-10】对于消息的命名,利用如下的方式:
发送方+接收方+事件描述+消息类型。
发送方:
发送消息的Task名或队列名。
接收方:
接收消息的Task名或队列名。
事件描述:
该消息携带的事件所实现的功能描述。
本案中涉及到的消息类型有:
请求(REQ)、应答(RSP)和通知(NTC)。
例如:
SYPC_EP_START_REQ。
标准字典
【规则3-2-1】要为项目成立一个标准字典,寄存该项目中所有标准的命名单词。
表3-1标准字典
例如:
英文
中文
备注
Add
添加
成对使用
Remove
移除
Insert
插入
成对使用
Delete
删除
Update
更新
Update
Cnt
计数
Count
Num
数字
Number的缩写
Info
信息
Information的缩写
Max
最大
Maximize的缩写
Min
最小
Minimize的缩写
Pass
密码
Password的缩写
Init
初始化
Initialize的缩写
Msg
消息
Message的缩写
Tmp
临时
Temp的缩写
Decl
声明
Declare的缩写
Exist
存在
Exist
Create
创建
Create
新建
Dest
目的
Destination的缩写
Src
源
Source的缩写
Val
值
Value的缩写
Rtn
返回
Return的缩写
以上的标准字典仅供参考,具体的字典要视每一个项目的具体情形而定。
4.注释
【规则4-1-1】程序有效注释量应很多于30%。
【规则4-1-2】边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。
再也不有效的注释要删除。
【规则4-1-3】注释应当准确、易懂,避免注释有二义性。
【规则4-1-4】尽可能避免在注释中利用缩写,专门是不常常利用缩写。
【规则4-1-5】注释的位置应与被描述的代码相邻,放在代码的上方。
【规则4-1-6】变量和数组概念声明时,若是其命名不是充分自注释的,则应该加上相应的注释。
注意:
全局变量要有较详细的注释,包括对其功能、取值范围和存取时注意事项等的说明。
【规则4-1-7】分支语句(条件分支、循环语句等)必需编写注释。
【规则4-1-8】函数注释必需写出函数的目的/功能、输入参数、输出参数、返回值。
输入、输出参数都要写明参数所属类型,若是有取值范围的话也应该写出。
请参看示例4-1所示。
示例4-1函数注释
【规则4-1-9】注释统一利用英文,利用数字或字符串需要加上注释。
【规则4-1-10】注释与其上面的代码用空行隔开,有多行注释要在同列上对齐,请看示例4-2。
【规则4-1-11】对项目组规定的重要内容必需进行注释。
【规则4-1-12】在}结束处,若是不能一眼看到对应的{,需要把对应的进入条件作为注释。
例如:
}/*if(nCount > 20)*/
}/*while(nCount < 60)*/
【规则4-1-13】删除某一段代码时应该利用#if0/#endif,要对删除开始和结束的地方进行标注,要标注出作者和时刻,并对删除原因进行说明。
【规则4-1-14】添加或修改代码时,也要对修改开始和结束的地方进行标注。
要标注出作者、时刻和修改的理由。
参看示例4-2
示例4-2修改代码注释
【规则4-1-15】注释风格统一利用/**/。
大段代码的删除参照规则4-1-13。
5.程序版式
缩进
【规则5-1-1】程序块要采用缩进风格编写,缩进的空格数为4个。
空行
空行起着分隔程序段落的作用。
空行得体将使程序的布局加倍清楚。
空行不会浪费内存。
【规则5-2-1】在每一个函数声明以后、每一个函数概念结束以后都要加空行。
参见示例5-1(a)
【规则5-2-2】在一个函数体内,逻辑上紧密相关的语句之间不加空行,其它地方应加空行分隔。
参见示例5-1(b)。
示例5-1(a)函数之间的空行示例5-1(b)函数内部的空行
代码行
【规则5-3-1】一行代码只写一条语句。
如此的代码容易阅读,而且方便于写注释。
【规则5-3-2】if、for、while、do等语句自占一行,执行语句不得紧跟其后。
不论执行语句有多少都要加{}。
如此能够避免书写失误。
示例5-2(a)风格良好的代码行示例5-2(b)风格不良的代码行
对齐
【规则5-4-1】程序的分界符‘{’和‘}’应独占一行而且位于同一列,同时与引用它们的语句左对齐。
【规则5-4-2】{ }之内的代码块在‘{’右边空4格处左对齐。
示例5-3(a)风格良好的对齐示例5-3(b)风格不良的对齐
【规则5-4-3】switch语句对齐方式,case语句与大括号处于同一列,case下的语句空4格,左对齐,参看示例5-4。
示例5-4switch语句的对齐风格
修饰符的位置
【规则5-5-1】将修饰符*和&紧靠变量名。
例如:
char *strName;
int *x, y; /*此处y不会被误解为指针*/
6.语法规范
运算符的优先级
【规则6-1-1】代码行中的运算符比较多时,要用括号肯定表达式的操作顺序,避免利用默许的优先级。
例如:
word = (high << 8) | low;
if ((a | b) && (a & c));
switch 语句
【规则6-2-1】每一个case 语句的结尾不要忘了加break,不然将致使多个分支重叠(除非成心使多个分支重叠)。
【规则6-2-2】不要忘记最后那个default 分支。
即便程序真的不需要default 处置,也应该保留语句default :
break;
函数参数
【规则6-3-1】函数的参数的书写要完整。
若是函数没有参数,则用void填充。
例如:
voidSetValue(intnwidth,intnheight);/*良好的风格*/
voidSetValue(int,int);/*不良的风格*/
floatGetValue(void);/*良好的风格*/
floatGetValue();/*不良的风格*/
【规则6-3-2】尽可能避免函数有太多的参数。
若是无法避免过量的参数,可依照以下的方式书写:
示例6-1函数多参数书写格式
【规则6-3-3】函数至少要有一个return语句。
goto语句
【规则6-4-1】要少用、慎用goto语句。
若是必需利用goto,那么只能向下进行goto挪用,不能向上goto。
7.关于可自动添加注释的宏
概述
为了便于给代码添加注释,利用sourceinsight中提供的宏语言编写了可自动添加代码的
宏。
这些宏能够依照指定的格式自动添加各类所需的注释。
文件中包括了这些宏。
目前共编写了六个宏,如下:
(1)XXXX_InsertFileHeader。
(2)XXXX_InsertFuncNote。
(3)XXXX_CreateFuncNote。
(4)XXXX_DeleteNote。
(5)XXXX_ModifyNote。
(6)XXXX_Note。
功能
7.2.1.XXXX_InsertFileHeader
那个宏的功能是在当前文件的开始添加文件头注释。
注释的格式如下:
在利用宏时,最开始需要输入作者名。
示例7-1文件头注释书写格式
7.2.2XXXX_InsertFuncNote
那个宏的功能是在当前文件中所有已编写好的函数添加函数注释。
注释的格式如下:
示例7-2函数注释书写格式
7.2.3XXXX_CreateFuncNote
那个宏的功能是为新编写的单个函数添加函数注释。
注释的格式同上。
7.2.4XXXX_DeleteNote
那个宏的功能是为代码的添加删除注释。
注释格式如下:
选中想要删除的代码段后,执行此宏概念即可自动添加删除注释。
在利用宏时,最开始需要输入作者名。
示例7-3代码添加删除注释书写格式
7.2.5XXXX_ModifyNote
那个宏的功能是为代码的添加增加或修改的注释。
注释的格式如下:
示例7-4代码添加增加或修改注释书写格式
选中新添加或要修改的代码段后,执行此宏概念即可自动添加添加或修改注释。
在利用宏时,最开始需要输入作者名。
7.2.6XXXX_Note
那个宏的功能是在光标当前位置自动生成一对注释符号。
格式如下:
示例7-5代码注释符号书写格式
配置
(1)将文件放到sourceinsight的安装目录下。
(2)将文件添加到工程当中,从头同步工程文件。
(3)打开Options菜单,选择MenuAssignments。
(4)选择相应的宏,添加到Work菜单中,如图所示:
示例7-6sourceinsight配置说明
在左侧选择要添加的宏,在右边的Menu当选择Work,按Insert按钮进行添加,按Ok完成。
配置完成后的效果如图:
示例7-7sourceinsight配置完成效果图
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件 编码 命名 规范