软件设计规范

软件设计规范

制定：

审核：

批准：

文件编号生效日期版本号分

发

部

门

深圳市德卡科技有限公司文件编号

文件版本A1

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

目录

第一章、项目模块划分 (15)

一、模块划分 (15)

二、模块命名 (15)

第二章、文件格式 (16)

一、c文件格式说明： (16)

1、文件创建及修改说明区 (16)

2、头文件引用区 (16)

3、全局变量定义区 (17)

4、驱动函数区 (17)

5、应用函数区 (17)

6、文件结束说明 (18)

二、h文件格式说明 (18)

1、文件创建及修改说明区 (18)

2、防重调用定义 (18)

3、头文件引用 (18)

4、控制接口定义区 (19)

5、常量定义区 (19)

6、宏调用定义区 (19)

7、类型定义区 (19)

8、外部引用变量区 (20)

9、外部引用函数区 (20)

10、操作流程说明区 (20)

11、文件结束说明 (21)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

第三章、命名规则 (21)

一、函数命名规则 (21)

二、变量命名规则 (22)

三、宏命名规则 (22)

四、文件命名规则 (22)

五、新定义变量类型命名规则 (23)

六、命名注意事项： (23)

1、标识符命名基本原则 (23)

2、命名中若使用特殊约定或缩写，则要有注释说明 (23)

3、局部循环变量也必须按照变量命名规则来定义 (23)

4、不要用数字或较奇怪的字符来定义标识符 (23)

5、用正确的反义词组命名具有互斥意义的变量或相反动作的函数等 (24)

6、避免使用以下划线开始和结尾的定义 (24)

7、程序中不要出现仅靠大小写区分的相似的标识符 (24)

8、标识符缩写 (24)

9、函数名应准确描述函数的功能 (24)

10、避免使用无意义或含义不清的动词为函数命名 (24)

第四章、代码书写规范 (24)

一、基本原则 (25)

二、排版 (25)

1、缩进风格 (25)

2、不要使用【TAB】键 (25)

3、空行 (25)

4、语句长度要小于80个字符 (26)

5、长语句换行 (26)

6、长表达式换行 (26)

7、若函数的参数较长，则要进行适当的划分 (27)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

8、一行只写一条语句 (27)

9、括号{} (27)

10、语句缩进要求 (28)

11、分界符 (29)

12、空格 (30)

三、注释 (31)

1、注释量 (31)

2、函数头部注释 (31)

3、代码与注释同时修改 (31)

4、注释的内容要清楚、明了，含义准确，防止注释二义性 (31)

5、避免在注释中使用缩写，特别是非常用缩写 (31)

6、注释书写位置 (32)

7、变量、常量命名不能充分自注释的，必须加以注释 (32)

8、数据结构命名不能充分自注释的，必须加以注释 (33)

9、全局变量注释 (33)

10、注释要与说描述的内容进行同样的缩排 (33)

11、将注释与其上面的代码用空行隔开 (34)

12、连续case语句处理时，必须编写注释 (35)

13、代码或表达式的中间禁止插入注释 (36)

14、通过正确命名使代码成为自注释的 (36)

15、在代码的功能、意图层次上进行注释，提供有用、额外的信息 (37)

16、在程序块的结束行右方加注释标记，以表明某程序块的结束 (37)

17、注释格式 (37)

18、采用中文注释 (38)

19、使用#if0和#endif注释代码块 (38)

20、注释不能嵌套 (38)

四、代码可读性 (38)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

1、使用小括号明确表达式的操作顺序 (38)

2、用有意义的枚举和宏替代数字 (39)

3、源程序中关系较为紧密的代码应尽可能相邻 (39)

4、用多行简单语句替代复杂语句 (40)

五、变量，结构 (40)

1、公共变量 (40)

1.1、去掉没必要的公共变量 (40)

1.2、仔细定义并明确公共变量的含义、作用、取值范围及公共变量间的关系 (40)

1.3、明确公共变量与操作此公共变量的函数或过程的关系 (41)

1.4、要谨慎向公共变量传递数据 (41)

1.5、防止局部变量与公共变量同名。 (41)

1.6、公共变量仅由模块或函数创建和修改，其余模块和函数只能访问 (41)

2、局部变量 (41)

2.1、严禁使用未经初始化的变量作为右值 (41)

2.2、不使用与硬件或软件环境关系密切的变量 (41)

2.3、变量声明时，同一类型，不同意义的多个变量，要分行，便于区分 (41)

2.4、对只设置一次的变量，宜使用“const”限定词进行声明 (42)

2.5、避免在函数中使用static 局部变量 (42)

3、数组 (42)

3.1、数组大小及初始值要明确定义 (42)

3.2、数组、结构和联合的初始化列表应显式描述 (42)

4、结构、联合 (42)

4.1、结构的功能要单一，是针对一种事务的抽象 (42)

4.2、不要设计面面俱到、非常灵活的数据结构 (43)

4.3、不同结构间的关系不要过于复杂 (43)

4.4、结构中元素的个数应适中 (44)

4.5、结构体中元素的布局 (45)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

4.6、结构体设计要考虑兼容性 (46)

4.7、跨平台数据结构，要考虑字节顺序及对齐问题 (46)

4.8、struct或union类型中至少应有一个成员 (47)

4.9、struct或union类型的成员类型 (47)

5、枚举 (47)

5.1、枚举元素的初始化应完整 (47)

6、自定义数据类型 (48)

6.1、合理地设计数据并使用自定义数据类型 (48)

6.2、自定义数据类型命名要恰当 (48)

7、类型转换 (48)

7.1、谨慎使用数据类型的强制转换 (48)

7.2、了解编译系统默认的数据类型转换 (48)

7.3、应禁止signed 类型与unsigned 类型之间的隐式转化 (49)

7.4、应禁止int 类型与float 类型的隐式转化 (49)

8、指针 (49)

8.1、不应对指针变量使用强制类型转换赋值 (49)

8.2、不应把自动类型的局部变量的地址赋值给外部指针 (49)

8.3、指针的指针不应超过两级 (49)

8.4、指向不同数据类型的指针之间不应相互转换 (49)

8.5、指针转换过程中不应丢失指针的const、volatile属性 (49)

8.6、只有指向数组的指针才允许进行算术运算 (49)

8.7、只有指向同一数组的两个指针才允许相减 (50)

8.8、只有指向同一数组的两个指针才允许用>、>=、<和<=等关系运算符进行比较50

8.9、指针的索引值不应为负 (51)

8.10、不应对指针值可能为NULL的指针进行算术运算 (51)

8.11、调用返回类型为指针的函数后，应进行是否为空的判断 (51)

8.12、局部变量的地址不应在本对象消亡后传给另外一个对象 (51)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

8.13、一个未知大小的对象的指针不应成为加法或者减法操作的左操作数 (52)

六、函数 (52)

1、函数编写原则 (52)

1.1、明确函数功能，精确（而不是近似）地实现函数设计 (52)

1.2、函数的规模尽量限制在200行以内 (52)

1.3、一个函数仅完成一件功能 (52)

1.4、为简单功能编写函数 (52)

1.5、不要设计多用途面面俱到的函数 (53)

1.6、函数功能具有可预测性 (53)

1.7、函数功能具有独立性 (53)

1.8、防止函数出现随机内聚 (54)

1.9、功能不明确的较小函数，可以不必存在 (55)

1.10、设计高扇入、合理扇出（小于7）的函数 (55)

1.11、减少函数本身或函数间的递归调用 (55)

1.12、降低函数间的耦合度 (55)

2、函数参数 (56)

2.1、明确接口函数参数的合法性检查者 (56)

2.2、防止将函数的参数作为工作变量 (56)

2.3、避免设计多参数函数，不使用的参数从接口中去掉 (57)

2.4、非调度函数应减少或防止控制参数，尽量只使用数据参数 (57)

2.5、检查函数所有参数输入的有效性 (58)

2.6、检查函数所有非参数输入的有效性，如数据文件、公共变量等 (58)

2.7、调用函数时参数类型要一致 (58)

2.8、避免使用BOOL参数 (58)

2.9、在函数参数中不应使用static存储类标识符 (58)

2.10、函数参数数量 (58)

2.11、宜避免函数参数在调用中未被使用 (58)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

3、函数返回 (59)

3.1、对所调用函数的错误返回码要仔细、全面地处理 (59)

3.2、函数的返回值要清楚、明了，让使用者不容易忽视错误情况 (59)

3.3、函数返回值要与赋值变量类型一致 (59)

3.4、对于提供了返回值的函数，在引用时最好使用其返回值 (59)

3.5、函数只有一个出口 (59)

4、可重入函数 (59)

4.1、可重入函数使用局部变量 (59)

4.2、可重入函数使用全局变量 (59)

5、函数模块划分 (60)

5.1、仔细分析模块的功能，进行函数的划分和组织 (60)

5.2、如果多段代码重复做同一件事情，那么在函数的划分上可能存在问题 (60)

5.3、函数内部的代码结构顺序 (60)

6、循环语句 (61)

6.1、循环控制变量的类型应为整型 (61)

6.2、循环控制变量应为局部变量 (62)

6.3、for循环控制语句中的3 个表达式只应和循环控制相关 (62)

6.4、for循环不宜只执行一次 (62)

7、判断语句 (62)

7.1、不要轻易用条件分支去替换逻辑表达式 (62)

7.2、switch语句中不应只包含default语句 (62)

7.3、所有非空的switch case子句都应以break 语句结束 (62)

7.4、switch控制表达式不应是一个常量或逻辑表达式 (62)

7.5、每一个switch语句都应至少有一个case子句 (62)

7.6、case表达式的类型应与switch控制表达式的类型一致 (62)

7.7、case表达式的大小不应超过switch控制表达式的大小 (62)

8、赋值语句 (63)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

8.1、尽量不使用条件赋值语句 (63)

9、其他注意事项 (63)

9.1、避免函数中不必要语句，防止程序中的垃圾代码 (63)

9.2、在多任务操作系统的环境下编程，更要注意函数可重入性的构造 (63)

9.3、将常用较长变量用宏替代 (63)

七、预处理 (63)

1、宏 (63)

1.1、用宏定义表达式时，要使用完备的括号 (63)

1.2、将宏所定义的多条表达式放在大括号中 (64)

1.3、使用宏时，不允许参数发生变化 (64)

1.4、函数类宏调用时参数要完整 (65)

2、条件编译 (65)

2.1、预处理语句“#if”和“#endif”不应分散在不同的文件之中 (65)

2.2、被包含文件中的“#else”、“#elseif”、“#endif”不应与父文件中的“#if” 匹配 (65)

2.3、“#if”表达式中使用的宏应该已经被定义，并且“#if”表达式只能包含整型常量 65

2.4、宏如果需要被重定义，应该先用“#undef”解除前面的定义 (65)

八、中断 (65)

1、中断服务程序不应有返回值 (65)

2、中断服务程序中不应使用printf()函数 (65)

3、对于中断中使用到的非局部变量，在中断处理函数中应对其进行入栈保护 ..65

4、调用中断处理程序中的变量要进行开关中断处理 (65)

5、对于开关中断，要注意成对匹配 (66)

6、中断服务程序代码要简单化 (66)

九、程序可测性 (66)

1、原则 (66)

1.1、统一的调测开关及打印函数 (66)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

1.2、统一的打印信息串格式 (66)

1.3、正式软件产品中应把断言及其它调测代码去掉（即把有关的调测开关关掉）66

1.4、用调测开关切换软件的DEBUG版和正式版 (66)

1.5、软件DEBUG版和发行版在实现功能上具有一致性 (66)

1.6、构造测试环境和测试用例 (66)

1.7、预先设计程序调测的方法和手段及各种调测开关 (66)

1.8、调测开关应分为不同级别和类型 (67)

2、断言 (67)

2.1、使用断言来发现软件问题，提高代码可测性 (67)

2.2、用断言来检查程序正常运行时不应发生但在调测时有可能发生的非法情况68

2.3、不能用断言来检查最终产品肯定会出现且必须处理的错误情况 (68)

2.4、对较复杂的断言加上明确的注释 (68)

2.5、用断言确认函数的参数 (68)

2.6、用断言保证没有定义的特性或功能不被使用 (68)

2.7、用断言对程序开发环境（OS/Compiler/Hardware）的假设进行检查 (69)

2.8、编写防错程序，然后在处理错误之后可用断言宣布发生错误 (69)

十、程序效率 (70)

1、原则 (70)

1.1、编程时要经常注意代码的效率 (70)

1.2、提高代码效率的前提 (70)

1.3、局部效率应为全局效率服务 (71)

1.4、合理划分模块函数 (71)

1.5、不应花过多的时间拼命地提高调用不很频繁的函数代码效率 (71)

1.6、不要一味追求紧凑的代码 (71)

1.7、不应存在执行不到的代码 (71)

1.8、去掉没必要的全局变量 (71)

2、方法 (71)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

2.1、解决软件空间效率1 (71)

2.2、解决软件空间效率2 (72)

2.3、循环体内工作量最小化 (72)

2.4、仔细分析有关算法，并进行优化 (73)

2.5、仔细考查、分析系统及模块处理输入（如事务、消息等）的方式，并加以改进73

2.6、直接用汇编编写调用频繁或性能要求极高的函数 (73)

2.7、在多重循环中，应将最忙的循环放在最内层 (73)

2.8、尽量减少循环嵌套层次 (74)

2.9、尽量不在循环体内放置判断语句 (74)

2.10、尽量用乘法或其它方法代替除法，特别是浮点运算中的除法 (75)

2.11、应注意switch-case语句的使用 (75)

十一、程序质量 (76)

1、原则 (76)

1.1、代码质量保证优先原则 (76)

1.2、合理划分子模块，提高可移植性和可重用性 (76)

1.3、提供良好的接口界面 (76)

1.4、系统具有一定容错能力 (76)

2、方法 (76)

2.1、认真处理程序所能遇到的各种出错情况 (76)

2.2、系统运行之初，要初始化有关变量及运行环境，防止未经初始化的变量被引用76

2.3、系统运行之初，要对加载到系统中的数据进行一致性检查 (76)

2.4、严禁随意更改其它模块或系统的有关设置和配置 (76)

2.5、不能随意改变与其它模块的接口 (76)

2.6、防止内存操作越界 (76)

2.7、编程时，要防止差1错误 (77)

2.8、要时刻注意易混淆的操作符 (77)

2.9、条件判断语句必须处理所有情况 (78)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

2.10、不要用goto语句 (78)

2.11、尽量都采用标准语句和标准库函数 (78)

2.12、避免使用嵌入式汇编 (78)

2.13、精心构造算法，并对其性能、效率进行测试 (78)

2.14、对较关键的算法最好使用其它算法来确认 (78)

2.15、时刻注意表达式是否会上溢、下溢 (78)

2.16、使用变量时要注意其边界值的情况 (79)

2.17、注意程序代码是否超过系统有关限制 (79)

2.18、循环、分支层次不要超过五层 (79)

2.19、不要比较浮点数的相等 (79)

2.20、关注共用体的存储、对齐模式 (79)

2.21、头文件中不应有对象或函数的定义 (79)

2.22、不应单独使用小写字母“l”或大写字母“O”作为变量名 (79)

2.23、函数声明时参数不应只有类型名没有标识符 (80)

2.24、不应对有符号数进行位运算 (80)

2.25、无格式的字符型不应与负数常量和零比较 (80)

2.26、无符号值不应与负数常量比较 (80)

2.27、对变量进行移位操作应保证不会产生溢出和数据截短 (80)

2.28、不应在布尔表达式中使用赋值操作符 (80)

2.29、不应对布尔表达式进行算术或者位运算 (80)

2.30、表达式的值在任何求值顺序下应保持一致 (80)

2.31、应避免除数可能为0的情况出现 (81)

2.32、赋值运算符的左操作数不应进行转换操作，并且应该是一个可更改的对象81

2.33、sizeof操作符不应用在有单边作用的表达式上 (81)

2.34、留心具体语言及编译器处理不同数据类型的原则及有关细节 (81)

十二、代码代码编辑、编译、审查 (81)

1、打开编译器的所有告警开关对程序进行编译 (81)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

2、在产品软件（项目组）中，要统一编译开关选项 (81)

3、通过代码走读及审查方式对代码进行检查 (81)

4、测试部测试产品之前，应对代码进行抽查及评审 (82)

5、养成随时保存编写代码的习惯 (82)

6、同产品软件（项目组）内，最好使用相同的编辑器，并使用相同的设置选项82

7、要小心地使用编辑器提供的块拷贝功能编程 (82)

8、合理地设计软件系统目录，方便开发人员使用 (82)

附录A 常用数据类型及简写 (82)

附录B 常用单词及缩写 (83)

附录C 常见反义词组 (85)

附录D 常见命名规则 (87)

一、匈牙利命名法 (87)

二、骆驼（Camel）命名法 (87)

三、帕斯卡（Pascal）命名法 (87)

四、下划线命名法 (87)

生效日期

软件设计规范发行类别■新增□修订

发行部门研发中心

第一章、项目模块划分

一、模块划分

将整个项目按照功能进行模块划分，各个模块相互独立，每个模块由一系列c文件和h文件组成。简单功能的模块采用一个c文件和h文件接口，复杂功能的模块可能需要多个c文件和h文件。

二、模块命名

按照模块所实现功能的英文名称或者简写命名，全部采用小写字母，多于1个单词的中间加下划线。例如：

模块命名说明

液晶lcd.c

lcd.h

液晶初始化，字符、汉字和图片显示

lcd_fonts.c

lcd_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、文件结束说明

主要包含：

文件结束说明：End Of 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、操作流程说明区