软件设计规范方案.docx
《软件设计规范方案.docx》由会员分享，可在线阅读，更多相关《软件设计规范方案.docx（77页珍藏版）》请在冰豆网上搜索。
软件设计规范方案
软件设计规范
制定：
审核：
批准：
文件编号
生效日期
版本号
分
发
部
门
修订履历
序号
版本
修订内容
修订人
修订日期
会签与文件发放：
会签部门
会签人
会签日期
签收部门
签收人
签收日期
深圳市德卡科技有限公司
文件编号
文件版本
A1
生效日期
软件设计规范
发行类别
■新增□修订
发行部门
研发中心
第一章、项目模块划分
一、模块划分
将整个项目按照功能进行模块划分，各个模块相互独立，每个模块由一系列c文件和h文件组成。
简单功能的模块采用一个c文件和h文件接口，复杂功能的模块可能需要多个c文件和h文件。
二、模块命名
按照模块所实现功能的英文名称或者简写命名，全部采用小写字母，多于1个单词的中间加下划线。
例如：
模块
命名
说明
液晶
lcd.c
lcd.h
液晶初始化，字符、汉字和图片显示
lcd_fonts.clcd_fonts.h
液晶自定义字库
按键
key.c
key.h
按键初始化，键值列表，取按键值
指示灯
led.c
led.h
指示灯初始化，闪烁控制
数码管
ledseg.c
ledseg.h
数码管初始化，数字显示，特殊字符显示
蜂鸣器
beep.c
beep.h
蜂鸣器初始化，鸣叫控制
第二章、文件格式
一、c文件格式说明：
1、文件创建及修改说明区
主要包含：
公司信息：
公司名称、公司网站。
创建信息：
创建者名称，创建日期，最初版本号，文档内容描述。
修改信息：
修改者名称，修改日期，修改后版本号，修改内容描述。
可参考模块《template.c》
说明：
与硬件相关的文件可以在此增加说明，如芯片型号等。
2、头文件引用区
主要包含：
系统头文件引用：
文件名包含在尖括号中。
自定义头文件引用：
文件名包含着双引号中。
可参考模块《template.c》
3、全局变量定义区
主要包含：
全局变量定义区说明注释行：
全局变量定义：
要赋初值。
全局变量注释：
可参考模块《template.c》。
4、驱动函数区
主要包含：
驱动函数区说明注释行：
函数说明：
包含函数说明，参数说明，返回值说明。
函数体：
可参考模块《template.c》
5、应用函数区
主要包含：
应用函数区说明注释行：
函数说明：
包含函数功能说明，参数说明，返回值说明。
函数体：
可参考模块《template.c》
6、文件结束说明
主要包含：
文件结束说明：
EndOfFile
可参考模块《template.c》
二、h文件格式说明
1、文件创建及修改说明区
主要包含：
公司信息：
公司名称、公司网站。
创建信息：
创建者名称，创建日期，最初版本号，文档内容描述。
修改信息：
修改者名称，修改日期，修改后版本号，修改内容描述。
可参考模块《template.h》
2、防重调用定义
命名规则：
下划线+文件名大写+下划线+文件类型H+下划线
可参考模块《template.h》
3、头文件引用
主要包含：
系统头文件引用：
文件名包含在尖括号中。
自定义头文件引用：
文件名包含着双引号中。
可参考模块《template.h》
4、控制接口定义区
主要包含：
控制口线定义区说明注释行：
接口定义：
全部采用大写字母，单词间以下划线分割
注释说明：
可参考模块《template.h》
5、常量定义区
主要包含：
常量定义区说明注释行：
常量定义：
全部采用大写字母，单词间以下划线分割
注释说明：
可参考模块《template.h》
6、宏调用定义区
主要包含：
宏调用定义区说明注释行：
宏调用处理：
注释说明：
可参考模块《template.h》
7、类型定义区
主要包含：
类型定义区说明注释行：
类型定义：
注释说明：
结构体成员要单独说明。
可参考模块《template.h》
8、外部引用变量区
主要包含：
外部应用变量区说明注释行：
引用变量声明：
以extern关键字开始
注释说明：
可参考模块《template.h》
9、外部引用函数区
主要包含：
外部应用函数区说明注释行：
函数注释说明：
包含函数功能说明，参数说明，返回值说明
引用函数声明：
以extern关键字开始
可参考模块《template.h》
10、操作流程说明区
主要包含：
操作流程说明区说明注释行：
模块执行流程说明：
说明要详细，执行步骤要明确。
可参考模块《template.h》
11、文件结束说明
主要包含：
文件结束说明：
EndOfFile
可参考模块《template.h》
第三章、命名规则
一、函数命名规则
格式如下：
序号
说明
字体
选择
备注
1
模块名称
大写
必选
以最直观模式给用户区分不同的模块函数，采用模块英文名称或者简写
2
下划线
必选
间隔符
3
函数动作
首字母大写
必选
动作英文名称或者简写，最多2个单词
4
函数对象
首字母大写
可选
对象英文名称或者简写，最多2个单词
5
函数范围
首字母大写
可选
范围英文名称或者简写，最多2个单词
例如：
LCD_DispWord，表示液晶模块显示汉字
函数命名的一个重要原则是望文知意（其他人看到函数名就大体知道函数功能），必须考虑命名的准确性，命名体现函数的功能，而不要体现函数的实现方法。
二、变量命名规则
局部变量命名：
格式如下：
序号
说明
字体
选择
备注
1
变量类型
简写小写
必选
以最直观模式给用户区分不同的变量类型，最多2个字母长度，具体参考《附录A常用变量类型及简写》
2
变量修饰
首字母大写
可选
修饰词英文名称或者简写，最多2个单词
3
变量名称
首字母大写
必选
名称英文名称或者简写，最多2个单词
例如：
ucharucCurrentValue;表示无符号类型，当前值
数组变量命名时在局部变量类型前增加前缀字母“a”。
例如：
ucharaucSendBuff[10];
指针变量命名时在局部变量类型前增加前缀字母“p”。
例如：
uchar*pucReceiveBuff[10];
全局变量命名时在局部变量类型前增加前缀字母“g”和下划线。
静态变量命名时在局部变量类型前增加前缀字母“s”和下划线。
三、宏命名规则
格式如下：
序号
说明
字体
选择
备注
1
模块名称
大写
必选
以最直观模式给用户区分不同的模块宏，采用模块英文名称或者简写
2
下划线
必选
间隔符
3
功能名称
大写
必选
功能英文名称或者简写，最多2个单词
4
下划线
可选
间隔符
5
修饰词
大写
可选
修饰词英文名称或者简写，最多2个单词
例如：
#defineTMP_BUFF_MAX256//缓冲区最大长度
四、文件命名规则
格式如下（全部小写）：
序号
说明
字体
选择
备注
1
模块名称
小写
必选
采用模块英文名称或者简写
2
下划线
可选
_
3
分类名称
小写
可选
分类英文名称或者简写
4
顿号
必选
.
5
文件类型
小写
必选
代码文件（c），头文件（h）
例如：
液晶模块：
lcd_driver.clcd_driver.hlcd_fonts.clcd_fonts.h
按键模块：
key.ckey.h
五、新定义变量类型命名规则
新定义变量类型对变量进行命名时可以提出2个与其他类型不相同的字母前缀来表示，并在文件开始或者新类型定义时进行说明。
六、命名注意事项：
1、标识符命名基本原则
标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。
尽量采用英文命名，不可以用汉语拼音。
标识符的长度应当符合“min-length&&max-information”原则。
说明：
较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写。
参考《附录B常用单词及缩写》
2、命名中若使用特殊约定或缩写，则要有注释说明
说明：
应该在源文件的开始之处，对文件中所使用的缩写或约定，特别是特殊的缩写，进行必要的注释说明。
3、局部循环变量也必须按照变量命名规则来定义
说明：
变量，尤其是局部变量，如果用单个字符表示，很容易敲错（如i写成j），而编译时又检查不出来，有可能为了这个小小的错误而花费大量的查错时间。
4、不要用数字或较奇怪的字符来定义标识符
示例：
如下命名，使人产生疑惑。
#defineEXAMPLE_0_TEST
#defineEXAMPLE_1_TEST
voidTMP_SetSls00（ucharucSls）;
应改为有意义的单词命名
#defineEXAMPLE_UNIT_TEST
#defineEXAMPLE_ASSERT_TEST
voidTMP_SetUdtMsgSls（ucharucSls）;
5、用正确的反义词组命名具有互斥意义的变量或相反动作的函数等
说明：
可参考《附录C常见反义词组》下面是一些在软件中常用的反义词组。
示例：
uintuiMinSum;
uintuiMaxSum;
uintTMP_AddUser（uchar*pucUserName）;
uintTMP_DeleteUser（uchar*pucUserName）;
6、避免使用以下划线开始和结尾的定义
除了编译开关/头文件等特殊应用，应避免使用_EXAMPLE_TEST_之类以下划线开始和结尾的定义
7、程序中不要出现仅靠大小写区分的相似的标识符
例如：
uint uix, uiX; //变量x与X容易混淆
voidTMP_foo（uintuiX）; //函数foo与FOO容易混淆
voidTMP_FOO（floatfX）;
8、标识符缩写
命名时尽量不使用单词缩写，如果单词太长必须缩写，应该省略其中的元音字母，以便望文知意，如packet_header缩写为pkt_hdr，而不要缩写为pack_h。
常用单词缩写见《附录B常用单词及缩写》
9、函数名应准确描述函数的功能
10、避免使用无意义或含义不清的动词为函数命名
说明：
避免用含义不清的动词如process、handle等为函数命名，因为这些动词并没有说明要具体做什么。
第四章、代码书写规范
一、基本原则
制定规范的基本目的就是加强代码的可维护性，也就是说代码必须易于阅读，易于理解，易于测试，易于移植。
所有的代码必须采用ANSIC，标准函数原型必须采用ANSIC标准。
保持代码语句和结构简单清晰，避免使用复杂语句。
二、排版
1、缩进风格
程序块要采用缩进风格编写，缩进的空格数为4个。
预处理语句、全局数据、函数原型、标题、附加说明、函数说明、标号等均顶格书写。
语句块的“{”“}”配对对齐，并与其前一行对齐。
2、不要使用【TAB】键
【TAB】键在不同编辑器和打印机上因所设置空格数目不同而造成程序布局不整齐，从而导致代码缩排混乱。
可以采用空格键来替代，4个空格代替一个【TAB】键。
如果采用SourceInsight软件，可以设置按【TAB】键后自动用4个空格键替代。
3、空行
相对独立的程序块之间、变量说明之后必须加空行。
程序文件结构各部分之间空两行，若不必要也可只空一行，各函数实现之间一般空两行
示例：
如下例子不符合规范。
if（（ucCount==1）&&（ucRetCode==1））
{
if（ucStatus=='1'）
{
*pucErrCode=0;
returnEPRONTCENTER;
}
}
if（（ucCount==1）&&（ucRetCode==0））
{
*pucErrCode=EPRONTCENTER;
returnEPRONTCENTER;
}
应如下书写：
if（（ucCount==1）&&（ucRetCode==1））
{
if（ucStatus=='1'）
{
*pucErrCode=0;
returnEPRONTCENTER;
}
}
if（（ucCount==1）&&（ucRetCode==0））
{
*pucErrCode=EPRONTCENTER;
returnEPRONTCENTER;
}
4、语句长度要小于80个字符
一行语句以小于80字符为宜，不要写得过长。
过多的代码会导致显示器显示不足，从而降低代码阅读速度，代码打印时也会导致打印不足
5、长语句换行
较长的语句（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。
示例：
stPermCountMsg.ucHead.ucLen=TMP_TO_STAT_PERM_COUNT_LEN
+TMP_STAT_SIZE_PER_FRAM*sizeof（ulong）;
aucTaskTable[ucFrameId*TMP_STAT_TASK_CHECK_NUMBER+ucIndex]
=astAtPoi[ucIndex].ucStatus;
6、长表达式换行
循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首。
划分出的新行要进行适当的缩进，使排版整齐，语句可读。
示例：
if（（ucTaskNo&&（TMP_StatItemValid（ucStatItem）））
{
...//programcode
}
for（i=0,j=0;（i&&（j{
...//programcode
}
for（i=0,j=0;
（ii++,j++）
{
...//programcode
}
7、若函数的参数较长，则要进行适当的划分
8、一行只写一条语句
不允许把多个短语句写在一行中，即一行只写一条语句
示例：
如下例子不符合规范。
stRect.ucLength=0;stRect.ucWidth=0;
应如下书写
stRect.ucLength=0;
stRect.ucWidth=0;
9、括号{}
if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。
左大括号“{”后和右大括号“}”前不可出现代码，并且与引用他的语句左对齐。
示例：
如下例子不符合规范。
if（pUserCR==NULL）return;
应如下书写：
if（pUserCR==NULL）
{
return;
}
10、语句缩进要求
函数的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。
预处理指令不需要缩进，总是从行首开始。
即使预处理指令位于缩进代码块中，指令也应从行首开始
示例：
良好风格：
预处理指令均从行首开始
if（lopsided_score）
{
#ifDISASTER_PENDING//Correct--Startsatbeginningofline
DropEverything（）;
#ifNOTIFY
NotifyClient（）;
#endif
#endif
BackToNormal（）;
}
不良风格：
缩进的预处理指令
if（lopsided_score）
{
#ifDISASTER_PENDING//Wrong!
The"#if"shouldbeatbeginning
//ofline
DropEverything（）;
#endif//Wrong!
Donotindent"#endif"
BackToNormal（）;
}
11、分界符
程序块的分界符（如C/C++语言的大括号‘{’和‘}’）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。
在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
示例：
如下例子不符合规范。
for（...）{
...//programcode
}
if（...）
{
...//programcode
}
voidexample_fun（void）
{
...//programcode
}
应如下书写。
for（...）
{
...//programcode
}
if（...）
{
...//programcode
}
voidexample_fun（void）
{
...//programcode
}
12、空格
在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；
进行非对等操作时，如果是关系密切的操作符（一元操作符，成员操作符，数组下标）后不应加空格。
说明：
采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如果语句已足够清晰则括号内侧（即左括号后面和右括号前面）不需要加空格，多重括号间不必加空格，因为在C/C++语言中括号已经是最清晰的标志了。
在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。
给操作符留空格时不要连续留两个以上空格。
（1）、关键字之后要留空格，以突出关键字。
（2）、函数名之后不要留空格，紧跟左括号‘（’，以与关键字区别
（3）、‘（’向后紧跟，‘）’、‘,’、‘;’向前紧跟，紧跟处不留空格。
（4）、‘,’之后要留空格，
例如：
Function（x,y,z）。
（5）、如果‘;’不是一行的结束符号，其后要留空格
例如：
for（initialization;condition;update）
（6）、赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=”“>=”、
“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”,“^”等二元操作符的前后应当加一个
空格。
if（current_time>=MAX_TIME_VALUE）
a=b+c;
a*=2;
a=b^2;
（7）、"!
"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格。
*p='a';//内容操作"*"与内容之间
flag=!
isEmpty;//非操作"!
"与内容之间
p=&mem;//地址操作"&"与内容之间
i++;//"++","--"与内容之间
（8）、”[]”、"->"、"."前后不加空格。
p->id=pid;//"->"指针前后不加空格
（9）、指针定义符号*的前面加空格。
char*get_string（）
{
char*str;
}
（10）、对于表达式比较长的for语句和if语句，为了紧凑起见可以适当地去掉一些空格
例如：
for（i=0;i<10;i++）和if（（a<=b）&&（c<=d））
三、注释
1、注释量
一般情况下，源程序有效注释量必须在20％以上。
说明：
注释的原则是有助于对程序的阅读理解，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。
2、函数头部注释
每个函数头部都应该进行注释，包括函数实现的功能，参数说明，返回值等。
函数的头部注释要达到调用无需浏览函数，从注释区就能够了解该函数的全部信息。
函数功能：
该函数实现的具体功能，具有依赖关系的函数间在此进行说明。
参数：
如果参数值为已知，可以在此详细列表说明。
如果函数有调用全局变量，也要在此
进行详细说明。
返回：
函数返回值，对不同的返回值要进行详细说明。
3、代码与注释同时修改
边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。
不再有用的注释要删除。
4、注释的内容要清楚、明了，含义准确，防止注释二义性
说明：
错误的注释不但无益反而有害。
5、避免在注释中使用缩写，特别是非常用缩写
说明：
在使用缩写时或之前，应对缩写进行必要的说明。
6、注释书写位置
注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。
示例：
如下例子不符合规范。
例1：
//getreplicatesubsystemindexandnetindicator
ucRepssnInd=aucSsnData[ucIndex].ucRepssnIndex;
ucRepssnNi=aucSsnData[ucIndex].ucNi;
例2：
ucRepssnInd=aucSsnData[ucIndex].ucRepssnIndex;
ucRepssnNi=aucSsnData[ucIndex].ucNi;
//getreplicatesu
升级会员 