软件设计规范

文档软件设计规范制定：审核：批准：文件编号生效日期版本号分发部门修订履历序号版本修订内容修订人修订日期会签与文件发放：会签部门会签人会签日期签收部门签收人签收日期深圳市德卡科技有限公司文件编号文件版本A1生效日期软件设计规范发行类别■新增□修订发行部门研发中心目录HYPERLINK第一章、项目模块划分 15HYPERLINK一、模块划分 15HYPERLINK二、模块命名 15HYPERLINK第二章、文件格式 15HYPERLINK一、c文件格式说明： 16HYPERLINK1、文件创建及修改说明区 16HYPERLINK2、头文件引用区 16HYPERLINK3、全局变量定义区 16HYPERLINK4、驱动函数区 16HYPERLINK5、应用函数区 17HYPERLINK6、文件结束说明 17HYPERLINK二、h文件格式说明 17HYPERLINK1、文件创建及修改说明区 17HYPERLINK2、防重调用定义 18HYPERLINK3、头文件引用 18HYPERLINK4、控制接口定义区 18HYPERLINK5、常量定义区 19HYPERLINK6、宏调用定义区 19HYPERLINK7、类型定义区 19HYPERLINK8、外部引用变量区 19HYPERLINK9、外部引用函数区 20HYPERLINK10、操作流程说明区 20HYPERLINK11、文件结束说明 20HYPERLINK第三章、命名规则 21HYPERLINK一、函数命名规则 21HYPERLINK二、变量命名规则 21HYPERLINK三、宏命名规则 22HYPERLINK四、文件命名规则 22HYPERLINK五、新定义变量类型命名规则 22HYPERLINK六、命名注意事项： 22HYPERLINK1、标识符命名基本原则 23HYPERLINK2、命名中若使用特殊约定或缩写，则要有注释说明 23HYPERLINK3、局部循环变量也必须按照变量命名规则来定义 23HYPERLINK4、不要用数字或较奇怪的字符来定义标识符 23HYPERLINK5、用正确的反义词组命名具有互斥意义的变量或相反动作的函数等 23HYPERLINK6、避免使用以下划线开始和结尾的定义 23HYPERLINK7、程序中不要出现仅靠大小写区分的相似的标识符 23HYPERLINK8、标识符缩写 24HYPERLINK9、函数名应准确描述函数的功能 24HYPERLINK10、避免使用无意义或含义不清的动词为函数命名 24HYPERLINK第四章、代码书写规范 24HYPERLINK一、基本原则 24HYPERLINK二、排版 24HYPERLINK1、缩进风格 24HYPERLINK2、不要使用【TAB】键 24HYPERLINK3、空行 24HYPERLINK4、语句长度要小于80个字符 25HYPERLINK5、长语句换行 25HYPERLINK6、长表达式换行 26HYPERLINK7、若函数的参数较长，则要进行适当的划分 26HYPERLINK8、一行只写一条语句 26HYPERLINK9、括号{} 27HYPERLINK10、语句缩进要求 27HYPERLINK11、分界符 28HYPERLINK12、空格 29HYPERLINK三、注释 30HYPERLINK1、注释量 30HYPERLINK2、函数头部注释 30HYPERLINK3、代码与注释同时修改 31HYPERLINK4、注释的内容要清楚、明了，含义准确，防止注释二义性 31HYPERLINK5、避免在注释中使用缩写，特别是非常用缩写 31HYPERLINK6、注释书写位置 31HYPERLINK7、变量、常量命名不能充分自注释的，必须加以注释 32HYPERLINK8、数据结构命名不能充分自注释的，必须加以注释 32HYPERLINK9、全局变量注释 32HYPERLINK10、注释要与说描述的内容进行同样的缩排 32HYPERLINK11、将注释与其上面的代码用空行隔开 33HYPERLINK12、连续case语句处理时，必须编写注释 34HYPERLINK13、代码或表达式的中间禁止插入注释 36HYPERLINK14、通过正确命名使代码成为自注释的 36HYPERLINK15、在代码的功能、意图层次上进行注释，提供有用、额外的信息 36HYPERLINK16、在程序块的结束行右方加注释标记，以表明某程序块的结束 36HYPERLINK17、注释格式 37HYPERLINK18、采用中文注释 37HYPERLINK19、使用#if0和#endif注释代码块 37HYPERLINK20、注释不能嵌套 37HYPERLINK四、代码可读性 37HYPERLINK1、使用小括号明确表达式的操作顺序 37HYPERLINK2、用有意义的枚举和宏替代数字 38HYPERLINK3、源程序中关系较为紧密的代码应尽可能相邻 39HYPERLINK4、用多行简单语句替代复杂语句 39HYPERLINK五、变量，结构 40HYPERLINK1、公共变量 40HYPERLINK1.1、去掉没必要的公共变量 40HYPERLINK1.2、仔细定义并明确公共变量的含义、作用、取值范围及公共变量间的关系 40HYPERLINK1.3、明确公共变量与操作此公共变量的函数或过程的关系 40HYPERLINK1.4、要谨慎向公共变量传递数据 40HYPERLINK1.5、防止局部变量与公共变量同名。 40HYPERLINK1.6、公共变量仅由模块或函数创建和修改，其余模块和函数只能访问 40HYPERLINK2、局部变量 41HYPERLINK2.1、严禁使用未经初始化的变量作为右值 41HYPERLINK2.2、不使用与硬件或软件环境关系密切的变量 41HYPERLINK2.3、变量声明时，同一类型，不同意义的多个变量，要分行，便于区分 41HYPERLINK2.4、对只设置一次的变量，宜使用“const”限定词进行声明 41HYPERLINK2.5、避免在函数中使用static局部变量 41HYPERLINK3、数组 41HYPERLINK3.1、数组大小及初始值要明确定义 41HYPERLINK3.2、数组、结构和联合的初始化列表应显式描述 41HYPERLINK4、结构、联合 42HYPERLINK4.1、结构的功能要单一，是针对一种事务的抽象 42HYPERLINK4.2、不要设计面面俱到、非常灵活的数据结构 43HYPERLINK4.3、不同结构间的关系不要过于复杂 43HYPERLINK4.4、结构中元素的个数应适中 44HYPERLINK4.5、结构体中元素的布局 44HYPERLINK4.6、结构体设计要考虑兼容性 45HYPERLINK4.7、跨平台数据结构，要考虑字节顺序及对齐问题 45HYPERLINK4.8、struct或union类型中至少应有一个成员 46HYPERLINK4.9、struct或union类型的成员类型 46HYPERLINK5、枚举 47HYPERLINK5.1、枚举元素的初始化应完整 47HYPERLINK6、自定义数据类型 47HYPERLINK6.1、合理地设计数据并使用自定义数据类型 47HYPERLINK6.2、自定义数据类型命名要恰当 47HYPERLINK7、类型转换 47HYPERLINK7.1、谨慎使用数据类型的强制转换 47HYPERLINK7.2、了解编译系统默认的数据类型转换 47HYPERLINK7.3、应禁止signed类型与unsigned类型之间的隐式转化 48HYPERLINK7.4、应禁止int类型与float类型的隐式转化 48HYPERLINK8、指针 48HYPERLINK8.1、不应对指针变量使用强制类型转换赋值 48HYPERLINK8.2、不应把自动类型的局部变量的地址赋值给外部指针 48HYPERLINK8.3、指针的指针不应超过两级 48HYPERLINK8.4、指向不同数据类型的指针之间不应相互转换 48HYPERLINK8.5、指针转换过程中不应丢失指针的const、volatile属性 48HYPERLINK8.6、只有指向数组的指针才允许进行算术运算 48HYPERLINK8.7、只有指向同一数组的两个指针才允许相减 49HYPERLINK8.8、只有指向同一数组的两个指针才允许用>、>=、<和<=等关系运算符进行比较 49HYPERLINK8.9、指针的索引值不应为负 50HYPERLINK8.10、不应对指针值可能为NULL的指针进行算术运算 50HYPERLINK8.11、调用返回类型为指针的函数后，应进行是否为空的判断 50HYPERLINK8.12、局部变量的地址不应在本对象消亡后传给另外一个对象 50HYPERLINK8.13、一个未知大小的对象的指针不应成为加法或者减法操作的左操作数 51HYPERLINK六、函数 51HYPERLINK1、函数编写原则 51HYPERLINK1.1、明确函数功能，精确（而不是近似）地实现函数设计 51HYPERLINK1.2、函数的规模尽量限制在200行以内 51HYPERLINK1.3、一个函数仅完成一件功能 51HYPERLINK1.4、为简单功能编写函数 51HYPERLINK1.5、不要设计多用途面面俱到的函数 52HYPERLINK1.6、函数功能具有可预测性 52HYPERLINK1.7、函数功能具有独立性 52HYPERLINK1.8、防止函数出现随机内聚 53HYPERLINK1.9、功能不明确的较小函数，可以不必存在 54HYPERLINK1.10、设计高扇入、合理扇出（小于7）的函数 54HYPERLINK1.11、减少函数本身或函数间的递归调用 54HYPERLINK1.12、降低函数间的耦合度 54HYPERLINK2、函数参数 55HYPERLINK2.1、明确接口函数参数的合法性检查者 55HYPERLINK2.2、防止将函数的参数作为工作变量 55HYPERLINK2.3、避免设计多参数函数，不使用的参数从接口中去掉 56HYPERLINK2.4、非调度函数应减少或防止控制参数，尽量只使用数据参数 56HYPERLINK2.5、检查函数所有参数输入的有效性 57HYPERLINK2.6、检查函数所有非参数输入的有效性，如数据文件、公共变量等 57HYPERLINK2.7、调用函数时参数类型要一致 57HYPERLINK2.8、避免使用BOOL参数 57HYPERLINK2.9、在函数参数中不应使用static存储类标识符 57HYPERLINK2.10、函数参数数量 57HYPERLINK2.11、宜避免函数参数在调用中未被使用 57HYPERLINK3、函数返回 58HYPERLINK3.1、对所调用函数的错误返回码要仔细、全面地处理 58HYPERLINK3.2、函数的返回值要清楚、明了，让使用者不容易忽视错误情况 58HYPERLINK3.3、函数返回值要与赋值变量类型一致 58HYPERLINK3.4、对于提供了返回值的函数，在引用时最好使用其返回值 58HYPERLINK3.5、函数只有一个出口 58HYPERLINK4、可重入函数 58HYPERLINK4.1、可重入函数使用局部变量 58HYPERLINK4.2、可重入函数使用全局变量 58HYPERLINK5、函数模块划分 59HYPERLINK5.1、仔细分析模块的功能，进行函数的划分和组织 59HYPERLINK5.2、如果多段代码重复做同一件事情，那么在函数的划分上可能存在问题 59HYPERLINK5.3、函数内部的代码结构顺序 59HYPERLINK6、循环语句 60HYPERLINK6.1、循环控制变量的类型应为整型 60HYPERLINK6.2、循环控制变量应为局部变量 61HYPERLINK6.3、for循环控制语句中的3个表达式只应和循环控制相关 61HYPERLINK6.4、for循环不宜只执行一次 61HYPERLINK7、判断语句 61HYPERLINK7.1、不要轻易用条件分支去替换逻辑表达式 61HYPERLINK7.2、switch语句中不应只包含default语句 61HYPERLINK7.3、所有非空的switchcase子句都应以break语句结束 61HYPERLINK7.4、switch控制表达式不应是一个常量或逻辑表达式 61HYPERLINK7.5、每一个switch语句都应至少有一个case子句 61HYPERLINK7.6、case表达式的类型应与switch控制表达式的类型一致 61HYPERLINK7.7、case表达式的大小不应超过switch控制表达式的大小 61HYPERLINK8、赋值语句 62HYPERLINK8.1、尽量不使用条件赋值语句 62HYPERLINK9、其他注意事项 62HYPERLINK9.1、避免函数中不必要语句，防止程序中的垃圾代码 62HYPERLINK9.2、在多任务操作系统的环境下编程，更要注意函数可重入性的构造 62HYPERLINK9.3、将常用较长变量用宏替代 62HYPERLINK七、预处理 62HYPERLINK1、宏 62HYPERLINK1.1、用宏定义表达式时，要使用完备的括号 62HYPERLINK1.2、将宏所定义的多条表达式放在大括号中 63HYPERLINK1.3、使用宏时，不允许参数发生变化 63HYPERLINK1.4、函数类宏调用时参数要完整 64HYPERLINK2、条件编译 64HYPERLINK2.1、预处理语句“#if”和“#endif”不应分散在不同的文件之中 64HYPERLINK2.2、被包含文件中的“#else”、“#elseif”、“#endif”不应与父文件中的“#if”匹配 64HYPERLINK2.3、“#if”表达式中使用的宏应该已经被定义，并且“#if”表达式只能包含整型常量 64HYPERLINK2.4、宏如果需要被重定义，应该先用“#undef”解除前面的定义 64HYPERLINK八、中断 64HYPERLINK1、中断服务程序不应有返回值 64HYPERLINK2、中断服务程序中不应使用printf()函数 64HYPERLINK3、对于中断中使用到的非局部变量，在中断处理函数中应对其进行入栈保护 64HYPERLINK4、调用中断处理程序中的变量要进行开关中断处理 64HYPERLINK5、对于开关中断，要注意成对匹配 64HYPERLINK6、中断服务程序代码要简单化 65HYPERLINK九、程序可测性 65HYPERLINK1、原则 65HYPERLINK1.1、统一的调测开关及打印函数 65HYPERLINK1.2、统一的打印信息串格式 65HYPERLINK1.3、正式软件产品中应把断言及其它调测代码去掉（即把有关的调测开关关掉） 65HYPERLINK1.4、用调测开关切换软件的DEBUG版和正式版 65HYPERLINK1.5、软件DEBUG版和发行版在实现功能上具有一致性 65HYPERLINK1.6、构造测试环境和测试用例 65HYPERLINK1.7、预先设计程序调测的方法和手段及各种调测开关 65HYPERLINK1.8、调测开关应分为不同级别和类型 66HYPERLINK2、断言 66HYPERLINK2.1、使用断言来发现软件问题，提高代码可测性 66HYPERLINK2.2、用断言来检查程序正常运行时不应发生但在调测时有可能发生的非法情况 67HYPERLINK2.3、不能用断言来检查最终产品肯定会出现且必须处理的错误情况 67HYPERLINK2.4、对较复杂的断言加上明确的注释 67HYPERLINK2.5、用断言确认函数的参数 67HYPERLINK2.6、用断言保证没有定义的特性或功能不被使用 67HYPERLINK2.7、用断言对程序开发环境（OS/Compiler/Hardware）的假设进行检查 68HYPERLINK2.8、编写防错程序，然后在处理错误之后可用断言宣布发生错误 68HYPERLINK十、程序效率 69HYPERLINK1、原则 69HYPERLINK1.1、编程时要经常注意代码的效率 69HYPERLINK1.2、提高代码效率的前提 69HYPERLINK1.3、局部效率应为全局效率服务 69HYPERLINK1.4、合理划分模块函数 69HYPERLINK1.5、不应花过多的时间拼命地提高调用不很频繁的函数代码效率 70HYPERLINK1.6、不要一味追求紧凑的代码 70HYPERLINK1.7、不应存在执行不到的代码 70HYPERLINK1.8、去掉没必要的全局变量 70HYPERLINK2、方法 70HYPERLINK2.1、解决软件空间效率1 70HYPERLINK2.2、解决软件空间效率2 71HYPERLINK2.3、循环体内工作量最小化 71HYPERLINK2.4、仔细分析有关算法，并进行优化 72HYPERLINK2.5、仔细考查、分析系统及模块处理输入（如事务、消息等）的方式，并加以改进 72HYPERLINK2.6、直接用汇编编写调用频繁或性能要求极高的函数 72HYPERLINK2.7、在多重循环中，应将最忙的循环放在最内层 72HYPERLINK2.8、尽量减少循环嵌套层次 73HYPERLINK2.9、尽量不在循环体内放置判断语句 73HYPERLINK2.10、尽量用乘法或其它方法代替除法，特别是浮点运算中的除法 74HYPERLINK2.11、应注意switch-case语句的使用 74HYPERLINK十一、程序质量 74HYPERLINK1、原则 74HYPERLINK1.1、代码质量保证优先原则 74HYPERLINK1.2、合理划分子模块，提高可移植性和可重用性 75HYPERLINK1.3、提供良好的接口界面 75HYPERLINK1.4、系统具有一定容错能力 75HYPERLINK2、方法 75HYPERLINK2.1、认真处理程序所能遇到的各种出错情况 75HYPERLINK2.2、系统运行之初，要初始化有关变量及运行环境，防止未经初始化的变量被引用 75HYPERLINK2.3、系统运行之初，要对加载到系统中的数据进行一致性检查 75HYPERLINK2.4、严禁随意更改其它模块或系统的有关设置和配置 75HYPERLINK2.5、不能随意改变与其它模块的接口 75HYPERLINK2.6、防止内存操作越界 75HYPERLINK2.7、编程时，要防止差1错误 76HYPERLINK2.8、要时刻注意易混淆的操作符 76HYPERLINK2.9、条件判断语句必须处理所有情况 76HYPERLINK2.10、不要用goto语句 77HYPERLINK2.11、尽量都采用标准语句和标准库函数 77HYPERLINK2.12、避免使用嵌入式汇编 77HYPERLINK2.13、精心构造算法，并对其性能、效率进行测试 77HYPERLINK2.14、对较关键的算法最好使用其它算法来确认 77HYPERLINK2.15、时刻注意表达式是否会上溢、下溢 77HYPERLINK2.16、使用变量时要注意其边界值的情况 77HYPERLINK2.17、注意程序代码是否超过系统有关限制 78HYPERLINK2.18、循环、分支层次不要超过五层 78HYPERLINK2.19、不要比较浮点数的相等 78HYPERLINK2.20、关注共用体的存储、对齐模式 78HYPERLINK2.21、头文件中不应有对象或函数的定义 78HYPERLINK2.22、不应单独使用小写字母“l”或大写字母“O”作为变量名 78HYPERLINK2.23、函数声明时参数不应只有类型名没有标识符 78HYPERLINK2.24、不应对有符号数进行位运算 78HYPERLINK2.25、无格式的字符型不应与负数常量和零比较 78HYPERLINK2.26、无符号值不应与负数常量比较 79HYPERLINK2.27、对变量进行移位操作应保证不会产生溢出和数据截短 79HYPERLINK2.28、不应在布尔表达式中使用赋值操作符 79HYPERLINK2.29、不应对布尔表达式进行算术或者位运算 79HYPERLINK2.30、表达式的值在任何求值顺序下应保持一致 79HYPERLINK2.31、应避免除数可能为0的情况出现 79HYPERLINK2.32、赋值运算符的左操作数不应进行转换操作，并且应该是一个可更改的对象 79HYPERLINK2.33、sizeof操作符不应用在有单边作用的表达式上 79HYPERLINK2.34、留心具体语言及编译器处理不同数据类型的原则及有关细节 80HYPERLINK十二、代码代码编辑、编译、审查 80HYPERLINK1、打开编译器的所有告警开关对程序进行编译 80HYPERLINK2、在产品软件（项目组）中，要统一编译开关选项 80HYPERLINK3、通过代码走读及审查方式对代码进行检查 80HYPERLINK4、测试部测试产品之前，应对代码进行抽查及评审 80HYPERLINK5、养成随时保存编写代码的习惯 80HYPERLINK6、同产品软件（项目组）内，最好使用相同的编辑器，并使用相同的设置选项 80HYPERLINK7、要小心地使用编辑器提供的块拷贝功能编程 80HYPERLINK8、合理地设计软件系统目录，方便开发人员使用 80HYPERLINK附录A常用数据类型及简写 81HYPERLINK附录B常用单词及缩写 82HYPERLINK附录C常见反义词组 84HYPERLINK附录D常见命名规则 86HYPERLINK一、匈牙利命名法 86HYPERLINK二、骆驼（Camel）命名法 86HYPERLINK三、帕斯卡（Pascal）命名法 86四、下划线命名法 86第一章、项目模块划分一、模块划分将整个项目按照功能进行模块划分，各个模块相互独立，每个模块由一系列c文件和h文件组成。简单功能的模块采用一个c文件和h文件接口，复杂功能的模块可能需要多个c文件和h文件。二、模块命名按照模块所实现功能的英文名称或者简写命名，全部采用小写字母，多于1个单词的中间加下划线。例如：模块命名说明液晶lcd.clcd.h液晶初始化，字符、汉字和图片显示lcd_fonts.clcd_fonts.h液晶自定义字库按键key.ckey.h按键初始化，键值列表，取按键值指示灯led.cled.h指示灯初始化，闪烁控制数码管ledseg.cledseg.h数码管初始化，数字显示，特殊字符显示蜂鸣器beep.cbeep.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_MAX 256 //缓冲区最大长度四、文件命名规则格式如下（全部小写）：序号说明字体选择备注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_TESTvoidTMP_SetSls00(ucharucSls);应改为有意义的单词命名#defineEXAMPLE_UNIT_TEST#defineEXAMPLE_ASSERT_TESTvoidTMP_SetUdtMsgSls(ucharucSls);5、用正确的反义词组命名具有互斥意义的变量或相反动作的函数等说明：可参考《附录C常见反义词组》下面是一些在软件中常用的反义词组。示例：uintuiMinSum;uintuiMaxSum;uintTMP_AddUser(uchar*pucUserName);uintTMP_DeleteUser(uchar*pucUserName);6、避免使用以下划线开始和结尾的定义除了编译开关/头文件等特殊应用，应避免使用_EXAMPLE_TEST_之类以下划线开始和结尾的定义7、程序中不要出现仅靠大小写区分的相似的标识符例如：uintuix,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_MAX_TASK_NUMBER)&&(TMP_StatItemValid(ucStatItem))){...//programcode}for(i=0,j=0;(i<astBufferKeyword[ucWordIndex].ucWordLength)&&(j<stNewKeyword.ucWordLength);i++,j++){...//programcode}for(i=0,j=0;(i<usFirstWordLength)&&(j<ucSecondWordLength);i++,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--StartsatbeginningoflineDropEverything();#ifNOTIFYNotifyClient();#endif#endifBackToNormal();}不良风格：缩进的预处理指令if(lopsided_score){#ifDISASTER_PENDING//Wrong!The"#if"shouldbeatbeginning//oflineDropEverything();#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：//getreplicatesubsystemindexandnetindicatorucRepssnInd=aucSsnData[ucIndex].ucRepssnIndex;ucRepssnNi=aucSsnData[ucIndex].ucNi;例2：ucRepssnInd=aucSsnData[ucIndex].ucRepssnIndex;ucRepssnNi=aucSsnData[ucIndex].ucNi;//getreplicatesubsystemindexandnetindicator应如下书写//getreplicatesubsystemindexandnetindicatorucRepssnInd=aucSsnData[ucIndex].ucRepssnIndex;ucRepssnNi=aucSsnData[ucIndex].ucNi;7、变量、常量命名不能充分自注释的，必须加以注释对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必加注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。示例：//activestatistictasknumber#defineMAX_ACT_TASK_NUMBER1000#defineMAX_ACT_TASK_NUMBER1000//activestatistictasknumber8、数据结构命名不能充分自注释的，必须加以注释数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。示例：可按如下形式说明枚举/数据/联合结构。//sccpinterfacewithsccpuserprimitivemessagenameenumSCCP_USER_PRIMITIVE{N_UNITDATA_IND,//sccpnotifysccpuserunitdatacomeN_NOTICE_IND,//sccpnotifyusertheNo.7networkcannot//transmissionthismessageN_UNITDATA_REQ,//sccpuser'sunitdatatransmissionrequest};9、全局变量注释全局变量要有较详细的注释，包括对其功能、取值范围、以及存取时注意事项等的说明。10、注释要与说描述的内容进行同样的缩排说明：可使程序排版整齐，并方便注释的阅读与理解。示例：如下例子，排版不整齐，阅读稍感不方便。voidexample_fun(void){//codeonecommentsCodeBlockOne//codetwocommentsCodeBlockTwo}应改为如下布局。voidexample_fun(void){//codeonecommentsCodeBlockOne//codetwocommentsCodeBlockTwo}11、将注释与其上面的代码用空行隔开示例：如下例子，显得代码过于紧凑。//codeonecomments*/programcodeone//codetwocommentsprogramcodetwo应如下书写：//codeonecommentsprogramcodeone//codetwocommentsprogramcodetwo12、连续case语句处理时，必须编写注释对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。示例（注意斜体加粗部分）：caseCMD_UP:ProcessUp();break;caseCMD_DOWN:ProcessDown();break;caseCMD_FWD:ProcessFwd();if(...){...break;}else{ProcessCFW_B();//nowjumpintocaseCMD_A}caseCMD_A:ProcessA();break;caseCMD_B:ProcessB();break;caseCMD_C:ProcessC(); break;caseCMD_D:ProcessD();break;...13、代码或表达式的中间禁止插入注释说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。14、通过正确命名使代码成为自注释的通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释15、在代码的功能、意图层次上进行注释，提供有用、额外的信息说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。示例：如下注释意义不大。//ifreceive_flagisTRUEif(receive_flag)而如下的注释则给出了额外有用的信息。//ifmtpreceiveamessagefromlinksif(receive_flag)16、在程序块的结束行右方加注释标记，以表明某程序块的结束说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。示例：参见如下例子。if(...){//programcode while(index<MAX_INDEX){//programcode}/*endofwhile(index<MAX_INDEX)*///指明该条while语句结束}/*endofif(...)*///指明是哪条if语句结束17、注释格式语句、变量定义、宏定义注释使用“//……”格式语句块、函数说明使用“/*……*/”格式。18、采用中文注释注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。19、使用#if0和#endif注释代码块使用#if0和#endif注释代码块。例如：来注释一段较大的代码#if0#defineDISP_TBL_SIZE5//Sizeofdisplaybuffertable#defineDISP_MAX_X80//Max.numberofcharactersinXaxis#defineDISP_MAX_Y25//Max.numberofcharactersinYaxis#defineDISP_MASK0x5F#endif20、注释不能嵌套四、代码可读性1、使用小括号明确表达式的操作顺序注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。示例：下列语句中的表达式word=(high<<8)|low(1)if((a|b)&&(a&c))(2)if((a|b)<(c&d))(3)如果书写为high<<8|lowa|b&&a&ca|b<c&d由于high<<8|low=(high<<8)|low,a|b&&a&c=(a|b)&&(a&c)，(1)(2)不会出错，但语句不易理解；a|b<c&d=a|（b<c）&d，(3)造成了判断条件出错。2、用有意义的枚举和宏替代数字避免使用不易理解的数字，用有意义的标识来替代。涉及物理状态或者含有物理意义的常量，不应直接使用数字，必须用有意义的枚举或宏来代替。示例：如下的程序可读性差。if(Trunk[index].trunk_state==0){Trunk[index].trunk_state=1;...//programcode}应改为如下形式： #defineTRUNK_IDLE0#defineTRUNK_BUSY1if(Trunk[index].trunk_state==TRUNK_IDLE){Trunk[index].trunk_state=TRUNK_BUSY;...//programcode}3、源程序中关系较为紧密的代码应尽可能相邻说明：便于程序阅读和查找。示例：以下代码布局不太合理。rect.length=10;char_poi=str;rect.width=5;若按如下形式书写，可能更清晰一些。rect.length=10;rect.width=5;//矩形的长与宽关系较密切，放在一起。char_poi=str;4、用多行简单语句替代复杂语句不要使用难懂的技巧性很高的语句，除非很有必要时。说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于算法。示例：如下表达式，考虑不周就可能出问题，也较难理解。*stat_poi+++=1;*++stat_poi+=1;应分别改为如下。*stat_poi+=1;stat_poi++;//此二语句功能相当于“*stat_poi+++=1;”++stat_poi;*stat_poi+=1;//此二语句功能相当于“*++stat_poi+=1;五、变量，结构 1、公共变量1.1、去掉没必要的公共变量说明：公共变量是增大模块间耦合的原因之一，故应减少没必要的公共变量以降低模块间的耦合度。1.2、仔细定义并明确公共变量的含义、作用、取值范围及公共变量间的关系说明：在对变量声明的同时，应对其含义、作用及取值范围进行注释说明，同时若有必要还应说明与其它变量的关系。1.3、明确公共变量与操作此公共变量的函数或过程的关系 明确公共变量与操作此公共变量的函数或过程的关系，如访问、修改及创建等。说明：明确过程操作变量的关系后，将有利于程序的进一步优化、单元测试、系统联调以及代码维护等。这种关系的说明可在注释或文档中描述。示例：在源文件中，可按如下注释形式说明。RELATIONSystem_InitInput_RecPrint_RecStat_ScoreStudentCreateModifyAccessAccessScoreCreateModifyAccessAccess,Modify注：RELATION为操作关系；System_Init、Input_Rec、Print_Rec、Stat_Score为四个不同的函数；Student、Score为两个全局变量；Create表示创建，Modify表示修改，Access表示访问。其中，函数Input_Rec、Stat_Score都可修改变量Score，故此变量将引起函数间较大的耦合，并可能增加代码测试、维护的难度。1.4、要谨慎向公共变量传递数据当向公共变量传递数据时，要十分小心，防止赋与不合理的值或越界等现象发生。说明：对公共变量赋值时，若有必要应进行合法性检查，以提高代码的可靠性、稳定性。1.5、防止局部变量与公共变量同名。说明：若使用了较好的命名规则，那么此问题可自动消除。1.6、公共变量仅由模块或函数创建和修改，其余模块和函数只能访问构造仅有一个模块或函数可以修改、创建，而其余有关模块或函数只访问的公共变量，防止多个不同模块或函数都可以修改、创建同一公共变量的现象。说明：降低公共变量耦合度。2、局部变量2.1、严禁使用未经初始化的变量作为右值说明：特别是在C/C++中引用未经赋值的指针，经常会引起系统崩溃。2.2、不使用与硬件或软件环境关系密切的变量使用严格形式定义的、可移植的数据类型，尽量不要使用与具体硬件或软件环境关系密切的变量。说明：使用标准的数据类型，有利于程序的移植。2.3、变量声明时，同一类型，不同意义的多个变量，要分行，便于区分示例：以下代码中，i,j,k是临时循环变量，与有实际意义的lenth,width放一起不太合理。intlength,width,i,j,k;若按如下形式书写，可能更清晰一些。intlength,width；inti,j,k;2.4、对只设置一次的变量，宜使用“const”限定词进行声明2.5、避免在函数中使用static局部变量尽量避免函数带有“记忆”功能，相同的输入应当产生相同的输出。带有“记忆”功能的函数，其行为可能是不可预测的，因为它的行为可能取决于某种“记忆状态”。这样的函数既不易理解又不利于测试和维护。3、数组3.1、数组大小及初始值要明确定义数组初始化不要采用系统默认值，最好能够采用初始化语句来完成3.2、数组、结构和联合的初始化列表应显式描述数组、结构和联合的初始化列表应使用大括号，并使用附加的大括号来指示嵌套的结构；程序员应显式地考虑和描述复杂数据类型的所有元素，不应忽略某个元素的初始化。例如：错误用法int16_ty[3][2]={1,2,3,4,5,6};int16_ty[3][2]={{1,2}};正确用法：int16_ty[3][2]={{1,2},{3,4},{54、结构、联合4.1、结构的功能要单一，是针对一种事务的抽象说明：设计结构时应力争使结构代表一种现实事务的抽象，而不是同时代表多种。结构中的各元素应代表同一事务的不同侧面，而不应把描述没有关系或关系很弱的不同事务的元素放到同一结构中。示例：如下结构不太清晰、合理。typedefstructSTUDENT_STRU{unsignedcharaucName[8];//student'snameunsignedcharucAge;//student'sageunsignedcharucSex;//student'ssex,asfollows//0-FEMALE;1-MALEunsignedcharaucTeacherName[8];//thestudentteacher'snameunisgnedcharucTeacherSex;//histeachersex}STUDENT;若改为如下，可能更合理些。typedefstructTEACHER_STRU{unsignedcharaucName[8];//teachernameunisgnedcharucSex;//teachersex,asfollows//0-FEMALE;1-MALE}TEACHER;typedefstructSTUDENT_STRU{unsignedcharaucName[8];//student'snameunsignedcharucAge;//student'sageunsignedcharucSex;//student'ssex,asfollows//0-FEMALE;1-MALEunsignedintucTeacherInd;//histeacherindex}STUDENT;4.2、不要设计面面俱到、非常灵活的数据结构说明：面面俱到、灵活的数据结构反而容易引起误解和操作困难。4.3、不同结构间的关系不要过于复杂说明：若两个结构间关系较复杂、密切，那么应合为一个结构。示例：如下两个结构的构造不合理。typedefstructPERSON_ONE_STRU{unsignedcharaucName[8];unsignedcharaucAddr[40];unsignedcharucSex;unsignedcharucCity[15];}PERSON_ONE;typedefstructPERSON_TWO_STRU{unsignedcharaucName[8];unsignedcharucAge;unsignedcharucTel;}PERSON_TWO;由于两个结构都是描述同一事物的，那么不如合成一个结构。typedefstructPERSON_STRU{unsignedcharaucName[8];unsignedcharucAge;unsignedcharucSex;unsignedcharaucAddr[40];unsignedcharaucCity[15];unsignedcharucTel;}PERSON;4.4、结构中元素的个数应适中若结构中元素个数过多可考虑依据某种原则把元素组成不同的子结构，以减少原结构中元素的个数。说明：增加结构的可理解性、可操作性和可维护性。示例：假如认为如上的_PERSON结构元素过多，那么可如下对之划分。typedefstructPERSON_BASE_INFO_STRU{unsignedcharucName[8];unsignedcharucAge;unsignedcharucSex;}PERSON_BASE_INFO;typedefstructPERSON_ADDRESS_STRU{unsignedcharucAddr[40];unsigne