软件设计规范Word格式.doc

1、5、应用函数区176、文件结束说明17二、h文件格式说明171、文件创建及修改说明区172、防重调用定义183、头文件引用184、控制接口定义区185、常量定义区196、宏调用定义区197、类型定义区198、外部引用变量区199、外部引用函数区2010、操作流程说明区2011、文件结束说明20第三章、命名规则21一、函数命名规则21二、变量命名规则21三、宏命名规则22四、文件命名规则22五、新定义变量类型命名规则22六、命名注意事项：221、标识符命名基本原则232、命名中若使用特殊约定或缩写，则要有注释说明233、局部循环变量也必须按照变量命名规则来定义234、不要用数字或较奇怪的字符来定

2、义标识符235、用正确的反义词组命名具有互斥意义的变量或相反动作的函数等236、避免使用以下划线开始和结尾的定义237、程序中不要出现仅靠大小写区分的相似的标识符238、标识符缩写249、函数名应准确描述函数的功能2410、避免使用无意义或含义不清的动词为函数命名24第四章、代码书写规范24一、基本原则24二、排版241、缩进风格242、不要使用【TAB】键243、空行244、语句长度要小于80个字符255、长语句换行256、长表达式换行267、若函数的参数较长，则要进行适当的划分268、一行只写一条语句269、括号2710、语句缩进要求2711、分界符2812、空格29三、注释301、注释量

3、302、函数头部注释303、代码与注释同时修改314、注释的内容要清楚、明了，含义准确，防止注释二义性315、避免在注释中使用缩写，特别是非常用缩写316、注释书写位置317、变量、常量命名不能充分自注释的，必须加以注释328、数据结构命名不能充分自注释的，必须加以注释329、全局变量注释3210、注释要与说描述的内容进行同样的缩排3211、将注释与其上面的代码用空行隔开3312、连续case语句处理时，必须编写注释3413、代码或表达式的中间禁止插入注释3614、通过正确命名使代码成为自注释的3615、在代码的功能、意图层次上进行注释，提供有用、额外的信息3616、在程序块的结束行右方加注释

4、标记，以表明某程序块的结束3617、注释格式3718、采用中文注释3719、使用 #if0和 #endif注释代码块3720、注释不能嵌套37四、代码可读性371、使用小括号明确表达式的操作顺序372、用有意义的枚举和宏替代数字383、源程序中关系较为紧密的代码应尽可能相邻394、用多行简单语句替代复杂语句39五、变量，结构401、公共变量401.1、去掉没必要的公共变量401.2、仔细定义并明确公共变量的含义、作用、取值范围及公共变量间的关系401.3、明确公共变量与操作此公共变量的函数或过程的关系401.4、要谨慎向公共变量传递数据401.5、防止局部变量与公共变量同名。401.6、公共变

5、量仅由模块或函数创建和修改，其余模块和函数只能访问402、局部变量412.1、严禁使用未经初始化的变量作为右值412.2、不使用与硬件或软件环境关系密切的变量412.3、变量声明时，同一类型，不同意义的多个变量，要分行，便于区分412.4、对只设置一次的变量，宜使用“const”限定词进行声明412.5、避免在函数中使用 static 局部变量413、数组413.1、数组大小及初始值要明确定义413.2、数组、结构和联合的初始化列表应显式描述414、结构、联合424.1、结构的功能要单一，是针对一种事务的抽象424.2、不要设计面面俱到、非常灵活的数据结构434.3、不同结构间的关系不要过于复

6、杂434.4、结构中元素的个数应适中444.5、结构体中元素的布局444.6、结构体设计要考虑兼容性454.7、跨平台数据结构，要考虑字节顺序及对齐问题454.8、struct或union类型中至少应有一个成员464.9、struct或union类型的成员类型465、枚举475.1、枚举元素的初始化应完整476、自定义数据类型476.1、合理地设计数据并使用自定义数据类型476.2、自定义数据类型命名要恰当477、类型转换477.1、谨慎使用数据类型的强制转换477.2、了解编译系统默认的数据类型转换477.3、应禁止 signed 类型与 unsigned 类型之间的隐式转化487.4、应禁

7、止 int 类型与 float 类型的隐式转化488、指针488.1、不应对指针变量使用强制类型转换赋值488.2、不应把自动类型的局部变量的地址赋值给外部指针488.3、指针的指针不应超过两级488.4、指向不同数据类型的指针之间不应相互转换488.5、指针转换过程中不应丢失指针的const、 volatile属性488.6、只有指向数组的指针才允许进行算术运算488.7、只有指向同一数组的两个指针才允许相减498.8、只有指向同一数组的两个指针才允许用、=、和=等关系运算符进行比较498.9、指针的索引值不应为负508.10、不应对指针值可能为NULL的指针进行算术运算508.11、调用返

8、回类型为指针的函数后，应进行是否为空的判断508.12、局部变量的地址不应在本对象消亡后传给另外一个对象508.13、一个未知大小的对象的指针不应成为加法或者减法操作的左操作数51六、函数511、函数编写原则511.1、明确函数功能，精确（而不是近似）地实现函数设计511.2、函数的规模尽量限制在200行以内511.3、一个函数仅完成一件功能511.4、为简单功能编写函数511.5、不要设计多用途面面俱到的函数521.6、函数功能具有可预测性521.7、函数功能具有独立性521.8、防止函数出现随机内聚531.9、功能不明确的较小函数，可以不必存在541.10、设计高扇入、合理扇出（小于7）的

9、函数541.11、减少函数本身或函数间的递归调用541.12、降低函数间的耦合度542、函数参数552.1、明确接口函数参数的合法性检查者552.2、防止将函数的参数作为工作变量552.3、避免设计多参数函数，不使用的参数从接口中去掉562.4、非调度函数应减少或防止控制参数，尽量只使用数据参数562.5、检查函数所有参数输入的有效性572.6、检查函数所有非参数输入的有效性，如数据文件、公共变量等572.7、调用函数时参数类型要一致572.8、避免使用BOOL参数572.9、在函数参数中不应使用static存储类标识符572.10、函数参数数量572.11、宜避免函数参数在调用中未被使用57

10、3、函数返回583.1、对所调用函数的错误返回码要仔细、全面地处理583.2、函数的返回值要清楚、明了，让使用者不容易忽视错误情况583.3、函数返回值要与赋值变量类型一致583.4、对于提供了返回值的函数，在引用时最好使用其返回值583.5、函数只有一个出口584、可重入函数584.1、可重入函数使用局部变量584.2、可重入函数使用全局变量585、函数模块划分595.1、仔细分析模块的功能，进行函数的划分和组织595.2、如果多段代码重复做同一件事情，那么在函数的划分上可能存在问题595.3、函数内部的代码结构顺序596、循环语句606.1、循环控制变量的类型应为整型606.2、循环控制变

11、量应为局部变量616.3、for循环控制语句中的3 个表达式只应和循环控制相关616.4、for循环不宜只执行一次617、判断语句617.1、不要轻易用条件分支去替换逻辑表达式617.2、switch语句中不应只包含default语句617.3、所有非空的switch case子句都应以break 语句结束617.4、switch控制表达式不应是一个常量或逻辑表达式617.5、每一个switch语句都应至少有一个case子句617.6、case表达式的类型应与switch控制表达式的类型一致617.7、case表达式的大小不应超过switch控制表达式的大小618、赋值语句628.1、尽量不使

12、用条件赋值语句629、其他注意事项629.1、避免函数中不必要语句，防止程序中的垃圾代码629.2、在多任务操作系统的环境下编程，更要注意函数可重入性的构造629.3、将常用较长变量用宏替代62七、预处理621、宏621.1、用宏定义表达式时，要使用完备的括号621.2、将宏所定义的多条表达式放在大括号中631.3、使用宏时，不允许参数发生变化631.4、函数类宏调用时参数要完整642、条件编译642.1、预处理语句“#if”和“#endif”不应分散在不同的文件之中642.2、被包含文件中的“#else”、“#elseif”、“#endif”不应与父文件中的“#if” 匹配642.3、“#i

13、f”表达式中使用的宏应该已经被定义，并且“#if”表达式只能包含整型常量642.4、宏如果需要被重定义，应该先用“#undef”解除前面的定义64八、中断641、中断服务程序不应有返回值642、中断服务程序中不应使用printf（）函数643、对于中断中使用到的非局部变量，在中断处理函数中应对其进行入栈保护644、调用中断处理程序中的变量要进行开关中断处理645、对于开关中断，要注意成对匹配646、中断服务程序代码要简单化65九、程序可测性651、原则651.1、统一的调测开关及打印函数651.2、统一的打印信息串格式651.3、正式软件产品中应把断言及其它调测代码去掉（即把有关的调测开关关掉

14、）651.4、用调测开关切换软件的DEBUG版和正式版651.5、软件DEBUG版和发行版在实现功能上具有一致性651.6、构造测试环境和测试用例651.7、预先设计程序调测的方法和手段及各种调测开关651.8、调测开关应分为不同级别和类型662、断言662.1、使用断言来发现软件问题，提高代码可测性662.2、用断言来检查程序正常运行时不应发生但在调测时有可能发生的非法情况672.3、不能用断言来检查最终产品肯定会出现且必须处理的错误情况672.4、对较复杂的断言加上明确的注释672.5、用断言确认函数的参数672.6、用断言保证没有定义的特性或功能不被使用672.7、用断言对程序开发环境（

15、OS/Compiler/Hardware）的假设进行检查682.8、编写防错程序，然后在处理错误之后可用断言宣布发生错误68十、程序效率691、原则691.1、编程时要经常注意代码的效率691.2、提高代码效率的前提691.3、局部效率应为全局效率服务691.4、合理划分模块函数691.5、不应花过多的时间拼命地提高调用不很频繁的函数代码效率701.6、不要一味追求紧凑的代码701.7、不应存在执行不到的代码701.8、去掉没必要的全局变量702、方法702.1、解决软件空间效率1702.2、解决软件空间效率2712.3、循环体内工作量最小化712.4、仔细分析有关算法，并进行优化722.5、

16、仔细考查、分析系统及模块处理输入（如事务、消息等）的方式，并加以改进722.6、直接用汇编编写调用频繁或性能要求极高的函数722.7、在多重循环中，应将最忙的循环放在最内层722.8、尽量减少循环嵌套层次732.9、尽量不在循环体内放置判断语句732.10、尽量用乘法或其它方法代替除法，特别是浮点运算中的除法742.11、应注意switch-case语句的使用74十一、程序质量741、原则741.1、代码质量保证优先原则741.2、合理划分子模块，提高可移植性和可重用性751.3、提供良好的接口界面751.4、系统具有一定容错能力752、方法752.1、认真处理程序所能遇到的各种出错情况752

17、.2、系统运行之初，要初始化有关变量及运行环境，防止未经初始化的变量被引用752.3、系统运行之初，要对加载到系统中的数据进行一致性检查752.4、严禁随意更改其它模块或系统的有关设置和配置752.5、不能随意改变与其它模块的接口752.6、防止内存操作越界752.7、编程时，要防止差1错误762.8、要时刻注意易混淆的操作符762.9、条件判断语句必须处理所有情况762.10、不要用goto语句772.11、尽量都采用标准语句和标准库函数772.12、避免使用嵌入式汇编772.13、精心构造算法，并对其性能、效率进行测试772.14、对较关键的算法最好使用其它算法来确认772.15、时刻注意

18、表达式是否会上溢、下溢772.16、使用变量时要注意其边界值的情况772.17、注意程序代码是否超过系统有关限制782.18、循环、分支层次不要超过五层782.19、不要比较浮点数的相等782.20、关注共用体的存储、对齐模式782.21、头文件中不应有对象或函数的定义782.22、不应单独使用小写字母“l”或大写字母“O”作为变量名782.23、函数声明时参数不应只有类型名没有标识符782.24、不应对有符号数进行位运算782.25、无格式的字符型不应与负数常量和零比较782.26、无符号值不应与负数常量比较792.27、对变量进行移位操作应保证不会产生溢出和数据截短792.28、不应在布尔

19、表达式中使用赋值操作符792.29、不应对布尔表达式进行算术或者位运算792.30、表达式的值在任何求值顺序下应保持一致792.31、应避免除数可能为0的情况出现792.32、赋值运算符的左操作数不应进行转换操作，并且应该是一个可更改的对象792.33、sizeof操作符不应用在有单边作用的表达式上792.34、留心具体语言及编译器处理不同数据类型的原则及有关细节80十二、代码代码编辑、编译、审查801、打开编译器的所有告警开关对程序进行编译802、在产品软件（项目组）中，要统一编译开关选项803、通过代码走读及审查方式对代码进行检查804、测试部测试产品之前，应对代码进行抽查及评审805、养

20、成随时保存编写代码的习惯806、同产品软件（项目组）内，最好使用相同的编辑器，并使用相同的设置选项807、要小心地使用编辑器提供的块拷贝功能编程808、合理地设计软件系统目录，方便开发人员使用80附录A 常用数据类型及简写81附录B 常用单词及缩写82附录C 常见反义词组84附录D 常见命名规则86一、匈牙利命名法86二、骆驼（Camel）命名法86三、帕斯卡（Pascal）命名法86四、下划线命名法86第一章、项目模块划分一、模块划分将整个项目按照功能进行模块划分，各个模块相互独立，每个模块由一系列c文件和h文件组成。简单功能的模块采用一个c文件和h文件接口，复杂功能的模块可能需要多个c文件

21、和h文件。二、模块命名按照模块所实现功能的英文名称或者简写命名，全部采用小写字母，多于1个单词的中间加下划线。例如：模块命名说明液晶lcd.c lcd.h液晶初始化，字符、汉字和图片显示lcd_fonts.c lcd_fonts.h液晶自定义字库按键key.c key.h按键初始化，键值列表，取按键值指示灯led.c led.h指示灯初始化，闪烁控制数码管ledseg.cledseg.h数码管初始化，数字显示，特殊字符显示蜂鸣器beep.cbeep.h蜂鸣器初始化，鸣叫控制第二章、文件格式1、文件创建及修改说明区主要包含：公司信息：公司名称、公司网站。创建信息：创建者名称，创建日期，最初版本号

22、，文档内容描述。修改信息：修改者名称，修改日期，修改后版本号，修改内容描述。可参考模块template.c说明：与硬件相关的文件可以在此增加说明，如芯片型号等。2、头文件引用区系统头文件引用：文件名包含在尖括号中。自定义头文件引用：文件名包含着双引号中。3、全局变量定义区全局变量定义区说明注释行：全局变量定义：要赋初值。全局变量注释：可参考模块template.c。4、驱动函数区驱动函数区说明注释行：函数说明：包含函数说明，参数说明，返回值说明。函数体：5、应用函数区应用函数区说明注释行：包含函数功能说明，参数说明，返回值说明。6、文件结束说明文件结束说明：End Of File二、h文件格式

23、说明可参考模块template.h2、防重调用定义命名规则：下划线+文件名大写+下划线+文件类型H+下划线3、头文件引用4、控制接口定义区控制口线定义区说明注释行：接口定义：全部采用大写字母，单词间以下划线分割注释说明：5、常量定义区常量定义区说明注释行：常量定义：6、宏调用定义区宏调用定义区说明注释行：宏调用处理：7、类型定义区类型定义区说明注释行：类型定义：结构体成员要单独说明。8、外部引用变量区外部应用变量区说明注释行：引用变量声明：以extern关键字开始9、外部引用函数区外部应用函数区说明注释行：函数注释说明：包含函数功能说明，参数说明，返回值说明引用函数声明：10、操作流程说明区操作流程说明区说明注释行：模块执行流程说明：说明要详细，执行步骤要明确。11、文件结束说明第三章、命名规则一、函数命名规则格式如下：字体选择备注1模块名称大写必选以最直观模式给用户区分不同的模块函数，采用模块英文名称或者简写2下划线间隔符3函数动作首字母大写动作英文名称或者简写，最多2个单词4函数对象可选对象英文名称或者简写，最多2个单词5函数范围范围英文名称或者简写，最多2个单词LCD_DispWord，表示液晶模块显示汉字 函数命名的一个重要原则是望文知意（其他