软件设计规范.docx
- 文档编号:29070172
- 上传时间:2023-07-20
- 格式:DOCX
- 页数:90
- 大小:327.28KB
软件设计规范.docx
《软件设计规范.docx》由会员分享,可在线阅读,更多相关《软件设计规范.docx(90页珍藏版)》请在冰豆网上搜索。
软件设计规范
软件设计规范
————————————————————————————————作者:
———————————————————————————————— 日期:
ﻩ
软件设计规范
制定:
审核:
批准:
文件编号
生效日期
版本号
分
发
部
门
修订履 历
序号
版本
修订内容
修订人
修订日期
会签与文件发放:
会签部门
会签人
会签日期
签收部门
签收人
签收日期
深圳市德卡科技有限公司
文件编号
文件版本
A1
生效日期
软件设计规范
发行类别
■新增 □修订
发行部门
研发中心
目 录
第一章、项目模块划分ﻩ15
二、模块命名15
第二章、文件格式15
一、c文件格式说明:
16
1、文件创建及修改说明区ﻩ16
2、头文件引用区ﻩ16
3、全局变量定义区ﻩ16
4、驱动函数区ﻩ16
5、应用函数区ﻩ17
6、文件结束说明ﻩ17
二、h文件格式说明ﻩ17
1、文件创建及修改说明区17
2、防重调用定义18
4、控制接口定义区ﻩ18
5、常量定义区ﻩ19
6、宏调用定义区19
7、类型定义区ﻩ19
8、外部引用变量区19
9、外部引用函数区20
10、操作流程说明区20
11、文件结束说明20
第三章、命名规则21
二、变量命名规则ﻩ21
三、宏命名规则ﻩ22
四、文件命名规则22
1、标识符命名基本原则ﻩ23
2、命名中若使用特殊约定或缩写,则要有注释说明23
3、局部循环变量也必须按照变量命名规则来定义ﻩ23
4、不要用数字或较奇怪的字符来定义标识符23
5、用正确的反义词组命名具有互斥意义的变量或相反动作的函数等23
7、程序中不要出现仅靠大小写区分的相似的标识符ﻩ23
8、标识符缩写24
9、函数名应准确描述函数的功能ﻩ24
10、避免使用无意义或含义不清的动词为函数命名ﻩ24
第四章、代码书写规范ﻩ24
一、基本原则ﻩ24
二、排版ﻩ24
1、缩进风格24
2、不要使用【TAB】键ﻩ24
5、长语句换行ﻩ25
6、长表达式换行ﻩ26
8、一行只写一条语句26
9、括号{}ﻩ27
10、语句缩进要求27
11、分界符ﻩ28
12、空格29
三、注释ﻩ30
1、注释量30
2、函数头部注释ﻩ30
3、代码与注释同时修改31
4、注释的内容要清楚、明了,含义准确,防止注释二义性31
5、避免在注释中使用缩写,特别是非常用缩写31
6、注释书写位置ﻩ31
7、变量、常量命名不能充分自注释的,必须加以注释32
8、数据结构命名不能充分自注释的,必须加以注释32
9、全局变量注释32
10、注释要与说描述的内容进行同样的缩排ﻩ32
11、将注释与其上面的代码用空行隔开ﻩ33
12、连续case语句处理时,必须编写注释34
13、代码或表达式的中间禁止插入注释36
14、通过正确命名使代码成为自注释的36
15、在代码的功能、意图层次上进行注释,提供有用、额外的信息36
16、在程序块的结束行右方加注释标记,以表明某程序块的结束ﻩ36
17、注释格式ﻩ37
18、采用中文注释ﻩ37
19、使用#if0和#endif注释代码块37
20、注释不能嵌套ﻩ37
四、代码可读性37
1、使用小括号明确表达式的操作顺序ﻩ37
2、用有意义的枚举和宏替代数字38
3、源程序中关系较为紧密的代码应尽可能相邻ﻩ39
4、用多行简单语句替代复杂语句ﻩ39
五、变量,结构40
1、公共变量40
1.1、去掉没必要的公共变量40
1.2、仔细定义并明确公共变量的含义、作用、取值范围及公共变量间的关系ﻩ40
1.3、明确公共变量与操作此公共变量的函数或过程的关系ﻩ40
1.5、防止局部变量与公共变量同名。
40
2、局部变量ﻩ41
2.1、严禁使用未经初始化的变量作为右值ﻩ41
2.2、不使用与硬件或软件环境关系密切的变量ﻩ41
2.4、对只设置一次的变量,宜使用“const”限定词进行声明ﻩ41
2.5、避免在函数中使用static局部变量41
3、数组ﻩ41
3.2、数组、结构和联合的初始化列表应显式描述ﻩ41
4、结构、联合ﻩ42
4.1、结构的功能要单一,是针对一种事务的抽象ﻩ42
4.4、结构中元素的个数应适中44
4.5、结构体中元素的布局44
4.6、结构体设计要考虑兼容性ﻩ45
4.8、struct或union类型中至少应有一个成员46
4.9、struct或union类型的成员类型46
5、枚举ﻩ47
5.1、枚举元素的初始化应完整47
6、自定义数据类型ﻩ47
6.1、合理地设计数据并使用自定义数据类型47
6.2、自定义数据类型命名要恰当ﻩ47
7、类型转换ﻩ47
7.2、了解编译系统默认的数据类型转换47
7.3、应禁止 signed类型与unsigned类型之间的隐式转化48
8、指针48
8.2、不应把自动类型的局部变量的地址赋值给外部指针ﻩ48
8.3、指针的指针不应超过两级ﻩ48
8.4、指向不同数据类型的指针之间不应相互转换ﻩ48
8.5、指针转换过程中不应丢失指针的const、volatile属性ﻩ48
8.6、只有指向数组的指针才允许进行算术运算ﻩ48
8.7、只有指向同一数组的两个指针才允许相减49
8.8、只有指向同一数组的两个指针才允许用>、>=、<和<=等关系运算符进行比较ﻩ49
8.10、不应对指针值可能为NULL的指针进行算术运算50
8.11、调用返回类型为指针的函数后,应进行是否为空的判断50
8.12、局部变量的地址不应在本对象消亡后传给另外一个对象50
8.13、一个未知大小的对象的指针不应成为加法或者减法操作的左操作数ﻩ51
六、函数ﻩ51
1、函数编写原则ﻩ51
1.1、明确函数功能,精确(而不是近似)地实现函数设计ﻩ51
1.2、函数的规模尽量限制在200行以内ﻩ51
1.3、一个函数仅完成一件功能51
1.5、不要设计多用途面面俱到的函数ﻩ52
1.6、函数功能具有可预测性52
1.7、函数功能具有独立性52
1.8、防止函数出现随机内聚ﻩ53
1.9、功能不明确的较小函数,可以不必存在ﻩ54
1.10、设计高扇入、合理扇出(小于7)的函数ﻩ54
1.11、减少函数本身或函数间的递归调用54
1.12、降低函数间的耦合度54
2.2、防止将函数的参数作为工作变量55
2.3、避免设计多参数函数,不使用的参数从接口中去掉ﻩ56
2.6、检查函数所有非参数输入的有效性,如数据文件、公共变量等ﻩ57
2.7、调用函数时参数类型要一致ﻩ57
2.8、避免使用BOOL参数ﻩ57
2.9、在函数参数中不应使用static存储类标识符ﻩ57
2.11、宜避免函数参数在调用中未被使用57
3、函数返回ﻩ58
3.1、对所调用函数的错误返回码要仔细、全面地处理58
3.2、函数的返回值要清楚、明了,让使用者不容易忽视错误情况ﻩ58
3.3、函数返回值要与赋值变量类型一致ﻩ58
3.4、对于提供了返回值的函数,在引用时最好使用其返回值58
3.5、函数只有一个出口58
4、可重入函数ﻩ58
4.1、可重入函数使用局部变量ﻩ58
4.2、可重入函数使用全局变量ﻩ58
5、函数模块划分ﻩ59
5.1、仔细分析模块的功能,进行函数的划分和组织59
5.2、如果多段代码重复做同一件事情,那么在函数的划分上可能存在问题ﻩ59
5.3、函数内部的代码结构顺序ﻩ59
6.1、循环控制变量的类型应为整型60
6.2、循环控制变量应为局部变量61
6.3、for循环控制语句中的3 个表达式只应和循环控制相关61
6.4、for循环不宜只执行一次61
7.1、不要轻易用条件分支去替换逻辑表达式ﻩ61
7.2、switch语句中不应只包含default语句ﻩ61
7.3、所有非空的switchcase子句都应以break 语句结束ﻩ61
7.4、switch控制表达式不应是一个常量或逻辑表达式ﻩ61
7.5、每一个switch语句都应至少有一个case子句ﻩ61
7.6、case表达式的类型应与switch控制表达式的类型一致61
8、赋值语句62
8.1、尽量不使用条件赋值语句ﻩ62
9、其他注意事项ﻩ62
9.1、避免函数中不必要语句,防止程序中的垃圾代码ﻩ62
9.2、在多任务操作系统的环境下编程,更要注意函数可重入性的构造62
9.3、将常用较长变量用宏替代62
七、预处理ﻩ62
1.3、使用宏时,不允许参数发生变化63
1.4、函数类宏调用时参数要完整64
2、条件编译64
2.1、预处理语句“#if”和“#endif”不应分散在不同的文件之中ﻩ64
2.2、被包含文件中的“#else”、“#elseif”、“#endif”不应与父文件中的“#if” 匹配ﻩ64
2.4、宏如果需要被重定义,应该先用“#undef”解除前面的定义ﻩ64
2、中断服务程序中不应使用printf()函数64
3、对于中断中使用到的非局部变量,在中断处理函数中应对其进行入栈保护64
4、调用中断处理程序中的变量要进行开关中断处理ﻩ64
5、对于开关中断,要注意成对匹配64
6、中断服务程序代码要简单化ﻩ65
九、程序可测性ﻩ65
1、原则ﻩ65
1.1、统一的调测开关及打印函数ﻩ65
1.2、统一的打印信息串格式ﻩ65
1.3、正式软件产品中应把断言及其它调测代码去掉(即把有关的调测开关关掉)ﻩ65
1.5、软件DEBUG版和发行版在实现功能上具有一致性65
1.6、构造测试环境和测试用例65
1.7、预先设计程序调测的方法和手段及各种调测开关65
1.8、调测开关应分为不同级别和类型66
2、断言ﻩ66
2.1、使用断言来发现软件问题,提高代码可测性ﻩ66
2.2、用断言来检查程序正常运行时不应发生但在调测时有可能发生的非法情况ﻩ67
2.3、不能用断言来检查最终产品肯定会出现且必须处理的错误情况ﻩ67
2.4、对较复杂的断言加上明确的注释ﻩ67
2.5、用断言确认函数的参数ﻩ67
2.6、用断言保证没有定义的特性或功能不被使用67
2.8、编写防错程序,然后在处理错误之后可用断言宣布发生错误ﻩ68
1.1、编程时要经常注意代码的效率ﻩ69
1.2、提高代码效率的前提69
1.3、局部效率应为全局效率服务ﻩ69
1.4、合理划分模块函数69
1.6、不要一味追求紧凑的代码70
1.7、不应存在执行不到的代码70
1.8、去掉没必要的全局变量ﻩ70
2、方法70
2.1、解决软件空间效率1ﻩ70
2.2、解决软件空间效率271
2.3、循环体内工作量最小化ﻩ71
2.4、仔细分析有关算法,并进行优化ﻩ72
2.6、直接用汇编编写调用频繁或性能要求极高的函数ﻩ72
2.7、在多重循环中,应将最忙的循环放在最内层ﻩ72
2.8、尽量减少循环嵌套层次ﻩ73
2.9、尽量不在循环体内放置判断语句73
2.11、应注意switch-case语句的使用ﻩ74
十一、程序质量ﻩ74
1、原则ﻩ74
1.2、合理划分子模块,提高可移植性和可重用性ﻩ75
1.3、提供良好的接口界面75
1.4、系统具有一定容错能力ﻩ75
2、方法ﻩ75
2.1、认真处理程序所能遇到的各种出错情况75
2.2、系统运行之初,要初始化有关变量及运行环境,防止未经初始化的变量被引用ﻩ75
2.3、系统运行之初,要对加载到系统中的数据进行一致性检查ﻩ75
2.4、严禁随意更改其它模块或系统的有关设置和配置ﻩ75
2.5、不能随意改变与其它模块的接口ﻩ75
2.6、防止内存操作越界ﻩ75
2.7、编程时,要防止差1错误76
2.8、要时刻注意易混淆的操作符ﻩ76
2.11、尽量都采用标准语句和标准库函数77
2.12、避免使用嵌入式汇编ﻩ77
2.14、对较关键的算法最好使用其它算法来确认ﻩ77
2.16、使用变量时要注意其边界值的情况77
2.17、注意程序代码是否超过系统有关限制ﻩ78
2.18、循环、分支层次不要超过五层78
2.19、不要比较浮点数的相等78
2.20、关注共用体的存储、对齐模式ﻩ78
2.22、不应单独使用小写字母“l”或大写字母“O”作为变量名ﻩ78
2.23、函数声明时参数不应只有类型名没有标识符ﻩ78
2.24、不应对有符号数进行位运算ﻩ78
2.25、无格式的字符型不应与负数常量和零比较ﻩ78
2.26、无符号值不应与负数常量比较ﻩ79
2.28、不应在布尔表达式中使用赋值操作符79
2.29、不应对布尔表达式进行算术或者位运算ﻩ79
2.30、表达式的值在任何求值顺序下应保持一致79
2.31、应避免除数可能为0的情况出现79
2.32、赋值运算符的左操作数不应进行转换操作,并且应该是一个可更改的对象79
2.33、sizeof操作符不应用在有单边作用的表达式上ﻩ79
十二、代码代码编辑、编译、审查80
1、打开编译器的所有告警开关对程序进行编译ﻩ80
2、在产品软件(项目组)中,要统一编译开关选项ﻩ80
3、通过代码走读及审查方式对代码进行检查80
4、测试部测试产品之前,应对代码进行抽查及评审80
5、养成随时保存编写代码的习惯80
6、同产品软件(项目组)内,最好使用相同的编辑器,并使用相同的设置选项ﻩ80
7、要小心地使用编辑器提供的块拷贝功能编程ﻩ80
8、合理地设计软件系统目录,方便开发人员使用ﻩ80
附录B常用单词及缩写ﻩ82
附录C常见反义词组ﻩ84
附录D常见命名规则ﻩ86
一、匈牙利命名法86
二、骆驼(Camel)命名法ﻩ86
四、下划线命名法86
第一章、项目模块划分
一、模块划分
将整个项目按照功能进行模块划分,各个模块相互独立,每个模块由一系列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、文件结束说明
主要包含:
文件结束说明:
EndOf File
可参考模块《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、文件结束说明
主要包含:
文件结束说明:
EndOf File
可参考模块《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_MAXﻩﻩ256ﻩ//缓冲区最大长度
四、文件命名规则
格式如下(全部小写):
序号
说明
字体
选择
备注
1
模块名称
小写
必选
采用模块英文名称或者简写
2
下划线
可选
_
3
分类名称
小写
可选
分类英文名称或者简写
4
顿号
必选
.
5
文件类型
小写
必选
代码文件(c),头文件(h)
例如:
液晶模块:
lcd_driver.clcd_driver.h lcd_fonts.clcd_fonts.h
按键模块:
key.ckey.h
五、新定义变量类型命名规则
新定义变量类型对变量进行命名时可以提出2个与其他类型不相同的字母前缀来表示,并在文件开始或者新类型定义时进行说明。
六、命名注意事项:
1、标识符命名基本原则
标识符的命名要清晰、明了,有明确含义,同时使用完整的单词或大家基本可以理解的缩写,避免使人产生误解。
尽量采用英文命名,不可以用汉语拼音。
标识符的长度应当符合“min-length &&max-information”原则。
说明:
较短的单词可通过去掉“元音”形成缩写;较长的单词可取单词的头几个字母形成缩写;一些单词有大家公认的缩写。
参考《附录B常用单词及缩写》
2、命名中若使用特殊约定或缩写,则要有注释说明
说明:
应该在源文件的开
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- 软件设计 规范
![提示](https://static.bdocx.com/images/bang_tan.gif)