软件设计规范

软件设计规范制定： 审核： 批准： 文件编号生效日期版本号分发部门 修 订 履 历序号 版本修订内容 修订人修订日期会签与文件发放：会签部门 会签人会签日期签收部门签收人签收日期 深圳市德卡科技有限公司文件编号文件版本A1生效日期软件设计规范发行类别新增 修订发行部门研发中心目 录第一章、项目模块划分15一、模块划分15二、模块命名15第二章、文件格式15一、c文件格式说明：161、文件创建及修改说明区162、头文件引用区163、全局变量定义区164、驱动函数区165、应用函数区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、不要用数字或较奇怪的字符来定义标识符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、注释量302、函数头部注释303、代码与注释同时修改314、注释的内容要清楚、明了，含义准确，防止注释二义性315、避免在注释中使用缩写，特别是非常用缩写316、注释书写位置317、变量、常量命名不能充分自注释的，必须加以注释328、数据结构命名不能充分自注释的，必须加以注释329、全局变量注释3210、注释要与说描述的内容进行同样的缩排3211、将注释与其上面的代码用空行隔开3312、连续case语句处理时，必须编写注释3413、代码或表达式的中间禁止插入注释3614、通过正确命名使代码成为自注释的3615、在代码的功能、意图层次上进行注释，提供有用、额外的信息3616、在程序块的结束行右方加注释标记，以表明某程序块的结束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、公共变量仅由模块或函数创建和修改，其余模块和函数只能访问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、不同结构间的关系不要过于复杂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、应禁止 int 类型与 float 类型的隐式转化488、指针488.1、不应对指针变量使用强制类型转换赋值488.2、不应把自动类型的局部变量的地址赋值给外部指针488.3、指针的指针不应超过两级488.4、指向不同数据类型的指针之间不应相互转换488.5、指针转换过程中不应丢失指针的const、 volatile属性488.6、只有指向数组的指针才允许进行算术运算488.7、只有指向同一数组的两个指针才允许相减498.8、只有指向同一数组的两个指针才允许用、=、和80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。示例： stPermCountMsg.ucHead.ucLen = TMP_TO_STAT_PERM_COUNT_LEN + TMP_STAT_SIZE_PER_FRAM * sizeof( ulong ); aucTaskTableucFrameId * TMP_STAT_TASK_CHECK_NUMBER + ucIndex = astAtPoiucIndex.ucStatus;6、长表达式换行循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首。划分出的新行要进行适当的缩进，使排版整齐，语句可读。示例：if (ucTaskNo TMP_MAX_TASK_NUMBER) & (TMP_StatItemValid (ucStatItem) . / program codefor (i=0, j=0; (i astBufferKeyworducWordIndex.ucWordLength) & (j stNewKeyword.ucWordLength); i+, j+) . / program codefor (i=0, j=0; (i usFirstWordLength) & (j =”、 “=”、“+”、“*”、“%”、“&”、“|”、“= 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; i10; i+)和if (a=b) & (c=d)三、注释1、注释量一般情况下，源程序有效注释量必须在20以上。说明：注释的原则是有助于对程序的阅读理解，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。2、函数头部注释每个函数头部都应该进行注释，包括函数实现的功能，参数说明，返回值等。函数的头部注释要达到调用无需浏览函数，从注释区就能够了解该函数的全部信息。函数功能：该函数实现的具体功能，具有依赖关系的函数间在此进行说明。参数：如果参数值为已知，可以在此详细列表说明。如果函数有调用全局变量，也要在此 进行详细说明。返回：函数返回值，对不同的返回值要进行详细说明。3、代码与注释同时修改边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。4、注释的内容要清楚、明了，含义准确，防止注释二义性说明：错误的注释不但无益反而有害。5、避免在注释中使用缩写，特别是非常用缩写说明：在使用缩写时或之前，应对缩写进行必要的说明。6、注释书写位置注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。示例：如下例子不符合规范。例1：/get replicate sub system index and net indicator ucRepssnInd = aucSsnDataucIndex.ucRepssnIndex;ucRepssnNi = aucSsnDataucIndex.ucNi;例2：ucRepssnInd = aucSsnDataucIndex.ucRepssnIndex;ucRepssnNi = aucSsnDataucIndex.ucNi;/get replicate sub system index and net indicator 应如下书写/get replicate sub system index and net indicator ucRepssnInd = aucSsnDataucIndex.ucRepssnIndex;ucRepssnNi = aucSsnDataucIndex.ucNi;7、变量、常量命名不能充分自注释的，必须加以注释对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必加注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。 示例：/active statistic task number #define MAX_ACT_TASK_NUMBER 1000#define MAX_ACT_TASK_NUMBER 1000 /active statistic task number8、数据结构命名不能充分自注释的，必须加以注释数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。 示例：可按如下形式说明枚举/数据/联合结构。/sccp interface with sccp user primitive message name enum SCCP_USER_PRIMITIVE N_UNITDATA_IND, /sccp notify sccp user unit data come N_NOTICE_IND, /sccp notify user the No.7 network can not /transmission this message N_UNITDATA_REQ, /sccp users unit data transmission request;9、全局变量注释全局变量要有较详细的注释，包括对其功能、取值范围、以及存取时注意事项等的说明。10、注释要与说描述的内容进行同样的缩排说明：可使程序排版整齐，并方便注释的阅读与理解。示例：如下例子，排版不整齐，阅读稍感不方便。void example_fun( void )/code one comments CodeBlock One / code two comments CodeBlock Two应改为如下布局。void example_fun( void ) /code one comments CodeBlock One /code two comments CodeBlock Two11、将注释与其上面的代码用空行隔开示例：如下例子，显得代码过于紧凑。/code one comments */program code one/code two commentsprogram code two应如下书写：/code one commentsprogram code one/code two commentsprogram code two12、连续case语句处理时，必须编写注释对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。示例（注意斜体加粗部分）：case CMD_UP: ProcessUp(); break;case CMD_DOWN: ProcessDown(); break;case CMD_FWD: ProcessFwd(); if (.) . break;elseProcessCFW_B(); / now jump into case CMD_Acase CMD_A: ProcessA(); break;case CMD_B: ProcessB(); break;case CMD_C: ProcessC(); break;case CMD_D: ProcessD(); break;.13、代码或表达式的中间禁止插入注释说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。14、通过正确命名使代码成为自注释的通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释15、在代码的功能、意图层次上进行注释，提供有用、额外的信息 说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。示例：如下注释意义不大。/if receive_flag is