代码规范V100.docx
- 文档编号:10138519
- 上传时间:2023-02-08
- 格式:DOCX
- 页数:43
- 大小:46.40KB
代码规范V100.docx
《代码规范V100.docx》由会员分享,可在线阅读,更多相关《代码规范V100.docx(43页珍藏版)》请在冰豆网上搜索。
代码规范V100
目录
第一篇致远电子软件规范-代码规范1
序言2
第1章变量、结构、类型3
1.1变量初始化3
1.2变量命名4
1.2.1全局变量的定义4
1.2.2局部变量的定义6
1.3结构变量与类型7
1.3.1模块内结构体命名与定义7
1.3.2应用程序内结构体命名与定义8
第2章语句、语句块、赋值与运算符10
2.1语句10
2.2语句块、赋值与运算符11
2.2.1关键字12
2.3结构化13
第3章函数、函数名及其参数14
3.1函数14
3.1.1函数的基本要求14
3.2函数名及其参数18
3.2.1函数命名规范18
3.2.2函数头缩进格式18
第4章可读性结构与标识符20
4.1可读性20
4.2标示符20
第5章注释、注释对齐22
5.1注释22
5.2注释对齐22
5.2.1行注释的对齐22
5.2.2函数体内的块注释22
5.2.3函数体外的块注释23
第6章宏定义与模块文件组织24
6.1编译预处理24
6.2模块文件的组织25
第7章文件相关26
7.1文件说明26
7.2函数开头的注释27
7.3其他29
第1篇致远电子软件规范-代码规范
序言
箴言
程序设计绝对是一门艺术,而不仅仅是一门技术。
首先,程序设计的出发点是给别人看,可读、易理解、好维护。
如果你的程序只能自己来维护,到你离开这个程序时,你程序也就与你一起离开了这个世界。
为了可读、易理解、好维护,你的程序要有好的设计,而不是一接手就进行东抄抄、西抄抄的写代码工作。
写代码是一个工程,程序设计是一种艺术;如果程序员只注重代码,那就像盖房子时的砌砖匠,只知道照图施工而已。
世界那么多令人叹为观止的美丽建筑物,那是设计家的艺术杰作,而不是砌砖匠的艺术杰作。
第1章变量、结构、类型
1.1变量初始化
不合理的初始化数据是产生编程错误的常见根源。
不恰当的变量初始化所导致的一系列问题都源于变量的默认初始值与预期的不同。
70%软件问题都源于内存错误,指针变量是错误的核心。
要求:
1:
尽量在定义变量的时候初始化。
2:
局部指针变量必须初始化。
3:
在使用全局变量时尽量进行有效范围检查,使用指针型全局变量必须进行有效性检查。
4:
尽量在靠近第一次使用变量的地方声明和定义变量。
例如,全局变量可以定义在初始化该变量的文件中。
5:
尽量避免使用全局变量,如果只在一个函数内使用的全局变量,尽量使用static变量。
如程序清单1.1所示。
程序清单1.1static变量使用范例
intGiStat=0;/*状态变量*/
voidledSwap(void)
{
if(GiStat==0){
GiStat=1;
ledOn();
}else{
GiStat=0;
ledOff();
}
}
以上程序应该改为如下程序
voidledSwap(void)
{
staticintiStat=0;
if(iStat==0){
iStat=1;
ledOn();
}else{
iStat=0;
ledOff();
}
}
6:
与第五条类似,如果某全局变量只在一个文件中使用,应定义为static变量。
1.2变量命名
为变量命名时最重要的考虑事项是,该名字要完全、准确地描述出该变量所代表的事物。
这个名字应该便于阅读,容易记忆,不能产生歧义。
变量名的长度,最佳的变量名长度应该在8到16个字符之间,当变量名太短时,需要花费大量的时间来判断变量的含义。
单字符的变量只能用于循环变量或者数组下标。
要求:
使用类匈牙利命名法。
变量名最多由三部分组成:
作用域、类型、描述。
1:
作用域:
该变量的作用范围,确定该变量的有效范围是在函数体外还是函数体内。
2:
类型:
该变量的类型,使用小写字符。
例如:
整形,字符型,单精度浮点型等等,还包括自定义的结构体类型。
3:
描述:
要完全、准确地描述出该变量所代表的事物,例如:
Max、Error、New等等。
1.2.1全局变量的定义
为了不污染用户命名空间,非应用程序(模块内部)使用的全局变量必须以双下划线开始“__”,后面紧跟一个大写的“G”字符,然后是变量类型,最后是该变量的描述。
变量类型为小写,C语言变量类型及其缩写定义,如表1.1所示。
类型为结构体的变量将在后续章节做出定义。
表1.1C语言变量类型及缩写定义
类型
缩写
整型(int、unsignedint、signedint)
i、ui、si
短整型(short、unsignedshort、signedshort)
s、us、ss
长整型(long、unsignedlong、signedlong)
l、ul、sl
浮点型(float、double)
f、d
字符型(char、unsignedchar、signedchar)
c、uc、sc
如果使用指针类型,则在缩写前加小写p,例如:
无符号长整型指针变量(unsignedlong*)缩写为:
pul。
变量类型后紧跟变量的描述,变量的描述以大写开始,例如:
Name、Error、New等等。
要求:
1:
禁止使用拼音作为变量的描述。
2:
变量名中间部分不允许使用下划线。
下面给出一些模块内部全局变量的定义范例。
例如,我们提供给用户一个直流电机控制软件包,软件包内定义了一些全局变量供我们自己使用,同时为了防止可能与用户自己定义的全局变量发生命名冲突,为了解决这种污染用户命名空间的问题,我们在定义模块内全局变量时要在前面加双下划线。
例如,我们定义GiMax变量,那么,用户在使用我们提供的软件包编写应用软件时,也定义GiMax为全局变量,编译连接时就会发生全局变量重复定义错误。
模块中的全局变量定义范例,如程序清单1.2所示。
程序清单1.2模块中的全局变量定义范例
int__GiMax;/*最大值*/
unsignedint__GuiErrorNumber;/*错误号*/
signedint__GsiStartValue=0;/*起始数值*/
char__GcFirst;/*第一个字符*/
char__GcName[]=“zlgmcu”;/*名字字符串*/
其他要求:
1:
在连续定义多个全局变量的时候必须对齐。
2:
右边加入对每一个全局变量作用的行注释。
3:
不允许使用TAB键作缩进。
(缩进单位为4个空格)
4:
在不同类型全局变量或不同含义的全局变量定义之间要加入空行。
如程序清单1.3所示。
在记录超时时间的三个变量和记录数据报个数的三个变量定义间加一个空行。
程序清单1.3变量定义中空行的使用范例
unsignedlong__ulIpDefaultTimeOut;/*IP数据报超时时间*/
unsignedlong__ulTcpDefaultTimeOut;/*TCP数据报超时时间*/
unsignedlong__ulUdpDefaultTimeOut;/*UDP数据报超时时间*/
unsignedlong__ulIpPackCounter;/*IP数据报计数器*/
unsignedlong__ulUdpPackCounter;/*UDP数据报计数器*/
unsignedlong__ulTcpPackCounter;/*TCP数据报计数器*/
5:
所有程序中,注释必须使用封闭式注释:
/*…*/。
6:
行注释的起始地点是第73个字符处,结束地点是第107个字符处。
7:
行注释的第一个字符地点是该行的第77个字符处(行注释的起始地点后两个空格处)
8:
变量类型必须写在一行的起始位置,除非含有extern关键字或者其他宏定义。
模块中指针型全局变量的定义与对齐,如程序清单1.4所示。
程序清单1.4模块中指针型全局变量的定义与对齐范例
int__GiMax;/*最大值*/
int*__GpiMax;/*最大值指针*/
int**__GppiMax;/*最大值双指针*/
要求:
1:
对齐的基准是英文字符或下划线。
2:
指针变量的类型字符前缀“p”紧跟类型名。
3:
指针变量标志“*”必须紧跟变量名。
例外情况,如程序清单1.5所示。
程序清单1.5“*”与变量名不贴近的例外情况范例
int*constiPtr2;
4:
禁止使用三重以上的指针。
在应用程序中定义的全局变量前面不需要加入双下划线:
“__”,如程序清单1.6所示。
程序清单1.6应用程序中的全局变量定义范例
intGiMax=0;/*最大值*/
intGiMin=0;/*最小值*/
intGiAverage=0;/*平均值*/
要求:
1:
变量有初始化时,赋值符号“=”左右必须使用空格。
2:
左端的空格的个数以上下对齐为准,右端的空格数为一个。
模块中指针型全局变量的定义,与非指针全局变量的对齐,如程序清单1.7所示。
程序清单1.7应用程序中指针型全局变量的定义与对齐范例
intGiMax;/*最大值*/
int*GpiMax;/*最大值指针*/
int**GppiMax;/*最大值双指针*/
含有extern关键字或者其他宏定义的变量书写范例,如程序清单1.8所示。
程序清单1.8含有extern关键字或者其他宏定义的变量书写范例
#defineEXTextern
externintGiMax;/*最大值*/
externint*GpiMax;/*最大值指针*/
externint**GppiMax;/*最大值双指针*/
EXTintGiMix;/*最小值*/
EXTint*GpiMix;/*最小值指针*/
EXTint**GppiMix;/*最小值双指针*/
要求:
1:
extern关键字或者其他宏定义必须写在一行的起始位置。
2:
extern关键字或者其他宏定义后面至少加一个空格。
3:
同类型或含义类似变量类型字段应该对齐。
1.2.2局部变量的定义
局部变量的定义与全局变量基本相同,但是,局部变量前不加双下划线“__”和作用域字符。
只包含变量类型和变量的描述。
下面给出一些全局变量的定义范例。
如程序清单1.9所示。
程序清单1.9局部变量定义范例
intiSheepCnt;/*绵羊的数量*/
int*piCarNumber=NULL;/*指向车辆数目的指针*/
要求:
1:
局部变量只包含变量类型和变量描述这两部分内容。
2:
定义局部指针型变量时,必须初始化为NULL或者一个有意义的地址,以减少发生错误的可能性。
不允许出现悬空指针(指向无效地址的指针,俗称:
野指针)。
3:
指针变量标志“*”必须紧跟变量名。
4:
变量名对齐时,指针符号应该向左移动,以英文字母或下划线作为起始对齐点。
5:
在不同类型局部变量或不同含义的局部变量定义之间要加入空行。
6:
函数的第一行代码与最后一个局部变量定义之间至少保留一个空行。
当变量定义中使用空行时,第一行代码与最后一个局部变量定义之间保留两个空行,其它情况保留一个空行。
指针型变量定义,如程序清单1.10所示。
程序清单1.10指针型局部变量定义范例
char*pcName=NULL;/*名字指针*/
int**ppiCarNumber=NULL;/*指向汽车数量指针地址的指针*/
局部变量中的特例:
循环变量与数组下标变量。
循环变量与数组下标变量允许超越以上要求,允许使用单字符变量名。
如程序清单1.11所示。
程序清单1.11局部循环变量与数组下标变量定义
inti;/*循环变量*/
shorts;/*数组下标*/
1.3结构变量与类型
1.3.1模块内结构体命名与定义
为了不污染用户命名空间,非应用程序(模块内部)使用的结构体与类型必须以双下划线开始“__”。
下面是一个非应用程序结构体定义范例,如程序清单1.12所示。
程序清单1.12模块内部结构体变量定义范例
struct__dlist{
intiValue;/*节点的数值*/
struct__dlist*pdlistNext;/*双链表前向指针*/
struct__dlist*pdlistPrev;/*双链表后向指针*/
};
typedefstruct__dlist__DLIST;/*定义类型*/
typedef__DLIST*__PDLIST;/*定义指针类型*/
如程序清单1.11所示。
结构体的名字应该能够准确描述出该变量所代表的事物,这里将双链表定义为“__dlist”,清晰易懂。
结构体变量名中间允许插入下划线。
组合关键字中间为一个空格,例如:
unsignedchar、typedefstruct等等。
要求:
1:
struct关键字必须写在一行的起始位置,一般在struct上部还有对该结构体全局性的描述,采用块注释结构。
2:
struct后只能加一个空格,然后键入结构体名。
3:
结构体名称必须为小写,非应用程序(模块内部)使用的结构体名字前,必须有双下划线“__”。
4:
结构体名字的后面加一个空格,然后键入“{”。
5:
结构体成员类型写在起始位置后四个空格处。
6:
一个结构体所有成员必须左对齐,以英文字母或下划线作为起始对齐点。
7:
在不同含义或不同类型的成员定义之间要加入空行。
8:
每个成员右边要跟有行注释。
9:
在最后一个成员的下一行起始位置写入:
“};”。
10:
不允许在结构体中使用位域。
如果程序中,需要使用类型来访问结构体,那么类型的定义必须紧跟结构体的定义。
定义类型时,如果程序需要访问该类型的指针,必须在该类型定义后,定义该类型的指针类型。
1.3.2应用程序内结构体命名与定义
在应用程序中定义的全局变量前面不需要加入双下划线:
“__”,如程序清单1.13所示。
程序清单1.13应用程序结构体变量定义范例
structdlist{
intiValue;/*节点的数值*/
structdlist*pdlistNext;/*双链表前向指针*/
structdlist*pdlistPrev;/*双链表后向指针*/
};
typedefstructdlistDLIST;/*定义类型*/
typedefDLIST*PDLIST;/*定义指针类型*/
/***************************************************************************
双链表表头指针全局变量定义
***************************************************************************/
PDLISTGpdlistHeader;/*表头指针*/
要求:
1:
当一个结构在程序中出现次数非常多,应该将此结构体定义为类型。
2:
对于编译器或CPU冲突的C类型,也可以写成结构,或者使用公司内部已经定义的通用结构。
例如:
将unsignedlong定义为INT32U等(使用µC/OS-II的相关类型定义)。
3:
严禁使用#define语句将C类型定义为宏。
如程序清单1.14所示,就会出现严重错误。
程序清单1.14#define语句定义的宏类型错误范例
#definePINTint*
PINTpiA,piB,piC;/*定义三个指针变量*/
以上代码只有piA为指针变量,其余都为int型变量。
4:
如果定义的是结构体类型,类型名尽量与结构体名统一。
下面给出部分类型定义范例,如程序清单1.15所示。
(模块内部类型前面加双下划线“__”)
程序清单1.15类型定义范例
typedefstructlistLIST;/*定义链表类型*/
typedefLIST*PLIST;/*定义链表指针类型*/
typedefstructudp_headerUDP_HEADER;/*UDP首部类型*/
typedefUDP_HEADER*PUDP_HEADER;/*UDP首部指针类型*/
typedefvoid(*PTASK)(void*);
/*任务类型指针*/
typedefvoidTASK(void*);/*任务类型*/
数据变量的类型定义要求:
1:
typedef关键字必须写在一行的起始处。
2:
typedef关键字后加一个空格,然后紧跟原始类型名。
3:
新定义的类型名要求左对齐,以英文字母或下划线作为起始对齐点。
4:
每个类型定义要有相关类型说明的行注释。
5:
当语句长度超过73个字符时,可以将行注释独立一行,放在下边。
(注释后加上空行)
6:
类型名必须全部大写,且必须是两个字符以上。
7:
指针类型的定义,起始字符必须是“P”。
8:
与结构体相同,类型名中间允许使用下划线。
函数类型及函数指针类型定义附加要求:
1:
函数或函数指针类型的类型名,与变量类型名要求对齐。
以英文字母或下划线作为起始对齐点。
2:
函数的返回类型名要求与变量类型定义的原始类型名对齐。
3:
函数参数括号要紧贴函数类型名。
其他函数定义及声明标准,见后面章节。
第2章语句、语句块、赋值与运算符
2.1语句
语句是组成函数与算法描述的最基本单元。
关于花括号的缩进方式,采用AT&T实验室K&R风格。
详细情况请阅读《RecommendedCstyleandcodingstandards》。
要求:
1:
语句要采用缩进风格编写,缩进的空格数为4个。
2:
关键字(非函数调用)后凡是带有括号“()”,在关键字和括号之间要加入一个空格。
括号后如有大括号,必须在打括号与“)”之间加入一个空格。
3:
较长的语句(>107个字符)必须分成多行书写,长表达式必须在低优先级操作符处划分新行。
划分出的新行要进行适当的缩进,使排版整齐,语句可读。
如程序清单2.1所示。
程序清单2.1长语句划分范例
MEMORY_COUNT_MSG.uiLen=NO7_TO_STAT_PERM_COUNT_LEN
+(STAT_SIZE_FILE_LEN*sizeof(char))
+(STAT_SIZE_PER_FRAM*sizeof(__XXXX));
4:
循环、判断等语句中若有较长的表达式或语句,则要进行适应的划分,长表达式要在低优先级操作符处划分新行,操作符放在末尾。
如程序清单2.2所示。
程序清单2.2循环、判断长语句划分范例
if(ucDestIp[0]==ucTemp[0]&&
ucDestIp[1]==ucTemp[1]&&
ucDestIp[2]==ucTemp[2]&&
ucDestIp[3]==ucTemp[3]){/*判断IP地址*/
__ethSendFrame(……);/*发送数据包*/
}
for(i=0;
(i<10&&pucTempName!
=NULL);
i+=2){/*for循环语句*/
……
}
5:
不允许把多个短语句写在一行中,即一行只写一条语句。
6:
if、for、do、while、case、switch、default等语句与相关条件和大括号自占一行,且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
7:
对齐只使用空格键,不使用TAB键。
8:
一行代码必须小于107字符。
2.2语句块、赋值与运算符
语句块是由诸多语句组成,要来完成某一项工作的语句集合。
语句块应该清晰、简洁。
要求:
1:
相对独立的语句块之间、变量说明之后必须加空行。
如程序清单2.3所示。
程序清单2.3空行的插入范例
if(!
pucName){/*名字为空*/
……/*相关处理代码*/
}
__MEN.puiArg=24;/*……*/
__MEN.puiWeight=60;/*……*/
如果出现连续赋值语句,等号需要对齐,等号左边至少留一个空格,右边必须留一个空格。
2:
函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格,case语句下的情况处理语句也要遵从语句缩进要求。
如程序清单2.4所示。
程序清单2.4case语句缩进范例
switch(pmsgM.iId){
caseMSG_ID_1:
/*分支1*/
……
break;/*跳出*/
caseMSG_ID_2:
/*分支2*/
……
break;/*跳出*/
default:
/*默认处理*/
……
}
case关键字和switch关键字对齐。
分支语句放在相应case关键字的下一行。
分支语句相对于case关键字的缩进是四个空格。
case后的条件与case之间相隔一个空格。
“:
”紧接着条件常量。
break关键
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 代码 规范 V100
![提示](https://static.bdocx.com/images/bang_tan.gif)