软件设计流程及编写规范.doc

一、前期方案评估1、主控芯片选型模块化控制要求，整理系统需要的资源。如系统时钟、普通IO拟需要的数目、中断源的个数、AD采样通道的个数、PWM输出的通道数等。在封装等外形尺寸等符合硬件标准的情况下，从上述方面去考虑主控芯片的型号，优先考虑行业通用或是编程人员熟悉的芯片类型。对于无参考的新品项目，在做方案时必须对主控芯片的资源做预留，以备功能扩展或是方案更改需要。如至少留出2个以上的普通IO口，1个以上的AD转换口，1个以上的中断资源。2、主控芯片性能粗测试初期选型通过的主控芯片，DIY一张DEMO实验板，编写测试程序测试所选芯片是否符合工程需要。主要测试单片机的如下性能：1） 系统时钟的稳定性2） 指令周期3） 端口输入输出延迟4） 极限工作温度区间5） 频漂6） 其它专用功能经测试后给出测试结论：Y/N。3、软件方案的制定3.1 系统资源分配系统时钟的选择（兼顾系统的运行速度以及实际需求），并非越高越好，如果控制系统要求有精确的定时，优先保证时间精度。如，精确的定时器触发、PWM精确的载波周期等。依据控制对象的具体情况，把控制需求模块化。对不同的功能模块，采用最适合的单片机资源去实现。对每个模块，详细分析模块的功能以及实现方式，对于核心功能，还需给出软件流程图。如要实现AD采样功能，需给出AD的参考电压、转换通道、转换精度等，并且给出采样值的滤波方法。3.2 系统结构框架设计设计系统的工作流程，把各功能模块按照一定的逻辑结构组合成完整的系统，其中包括系统框架图，软件流程图，中断管理等。对于中断，必须慎重考虑程序被打断后的恢复问题，如程序在运行到AD采样时被某中断打断，中断函数中依然有AD采样，那么在中端函数执行完后，程序在断点继续执行时AD采样寄存器的值已不再是中断执行前的值。3.3 任务进度安排指定软件编写责任人以及进度表。相应文档规整，责任人签字确认后存档。二、软件编写规范1、文档文件的结构原则：做到格式清晰、注释简明扼要、命名规范易懂、函数模块化、程序易读易维护、功能准确实现、代码空间效率和时间效率高1.1程序代码和工程空间程序源码和工程空间分别建立各自的文件夹，程序源代码命名时体现出版本序列，工程空间只体现项目名称不含版本号。软件版本升级的时候只需把旧版本的原程序代码文件备份，在工程空间重新加载新版本软件代码。如做一个电机用的控制系统，工程空间(workspace)的建立路径为：“E:MotorControlWorkspace-MotorControl”，源代码存放路径为：“E:MotorControlCode-MotorControl-V1.0”，如版本更新，只需更改源代码的版本，workspace重新加载新的源代码。1.2源代码的组织结构主函数、子函数、中断函数各单独建立一个.c文件，同时每个.c文件都应包含一个同名的.h文件（如果确实不需要，可以没有）。.c文件里面编写功能函数，同名的.h文件里面声明相应的变量以及宏定义。2、 标示符的命名标示符命名清晰明了，有明确含义，使用完整单词或是约定俗称的缩写。命名风格要自始至终保持一致，如命名中使用特殊约定或是缩写，要注释说明。2.1宏和常量命名宏和常量用全部大写字母来命名，词与词之间用下划线分隔。对程序中用到的数字均应用有意义的枚举或宏来代替。如：#define PWM_CYCLE6402.2 变量命名变量名用小写字母命名，每个词的第一个字母大写，注意长度适当，不要定义的过长。变量后缀类型表述变量的大写和数字类型，如果变量是全局变量则还需前缀“G_”。如：unsigned char CurrentValue_8u；signed int PresentSpeed_16s；extern unsigned int G_AverageSpeed_16u；2.3 函数命名函数名用小写字母命名，每个词的第一个字母大写。如：void SpeedSampling();3 注释有助于对程序的阅读理解，说明程序在做什么，解释代码的目的、功能和采用的方法。注释语言必须准确、易懂、简洁，边写代码边注释，修改代码同时修改相应的注释，不再有用的注释要删除。3.1 文件头注释文件头注释放在main函数的.c文件中，文件注释必须说明文件名、函数功能、创建人、创建日期、版本信息等相关信息。修改文件代码时，应在文件注释中记录修改日期、修改人员、修改信息及修改目的。文件注释放在文件顶端，用“/*/”格式包含。/*公司名称：创建者：创建日期：功能描述：包含文件：版本号：*修改时间：修改者：修改说明：新版本号：*/3.2 函数注释函数头部注释应包括函数名称、函数功能、入口参数、出口参数等内容。如有必要还可增加作者、创建日期、修改记录（备注）等相关项目。函数头部注释放在每个函数的顶端，用/*/的格式包含。其中函数名称应简写为Name()，不加入、出口参数等信息。/*函数名称：功能描述：创建者：创建日期：入口参数：出口参数：修改者：修改时间：修改说明：*/3.3 程序语句注释代码注释应与被注释的代码紧邻，放在其上方或右方，不可放在下面。如放于上方则需与其上面的代码用空行隔开。一般少量注释应该添加在被注释语句的行尾，一个函数内的多个注释左对齐；较多注释则应加在上方且注释行与被注释的语句左对齐。函数代码注释用/的格式。通常，分支语句（条件分支、循环语句等）必须编写注释。其程序块结束行的右方应加表明该程序块结束的标记end of , 尤其在多重嵌套时。例如：Switch (case)Case 1:;/end of case 1/Case 2:;/end of case 2/.;/end of switch/3.4 变量、常量、宏的注释同一类型的标识符应集中定义，并在定义之前一行对其共性加以统一注释。对单个标识符的注释加在定义语句的行尾。全局变量一定要有详细的注释，包括其功能、取值范围、哪些函数或过程存取它以及存取时的注意事项等。注释用/的格式。如：unsigned char CurrentValue_8u；/定义当前电流值为无符号字符型变量/4、 排版规范4.1 缩进代码的每一级均往右缩进4个空格，花括号“”，“”应独占一行并位于同一列，同时与引用它们的语句左对齐，如：for( ; ;)for( ; ;)if( )if( )program code;千万不能写成program code;.4.2分行过长的语句（超过80个字符）要分成多行书写，长表达式要在优先级操作符处划分新行，操作符放在新行之首，划分出的新行要适当的缩进，使排版整齐，语句易读，避免把注释插入分行中。如：if( ( very_longe_variable1 = very_longe_variable2 )&( very_longe_variable3 = very_longe_variable6 ) )/注释/programcode;4.3 空行1） 文件注释区、头文件引用区、函数间应该有且只有一行空行。2） 相邻函数之间应该有且只有一行空行。3） 函数体内相对独立的程序块之间可以用一行空行或注释分隔。4） 函数注释和对应的函数体之间不应该有空行。5） 文件末尾处有且只有一行空行。/ 空行void function1()Programcode;/ 空行void function2()Programcode;/空行4.4 空格1) 关键字之后要留空格。像const、case等关键字之后至少要留一个空格，否则无法辨析关键字。像if、for、while等关键字和紧跟的左括号（之后应留一个空格，右括号前也对应要留一个空格，以突出关键字。例如：if ( a=b )2) 函数名之后不要留空格，紧跟左括号，以与关键字区别。3) 函数形参之间应该有且只有一个空格（形参逗号后面加空格）。4) 同一行中定义的多个变量间应该有且只有一个空格（变量逗号后面加空格）。5) 表达式中，若有多个操作符连写的情况，应使用空格对它们分隔：6) 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符前后均加一个空格；在两个以上的关键字、变量、常量进行非对等操作时，其前后均不应加空格；7) 逗号只在后面加空格；8) 双目操作符，如比较操作符, 赋值操作符=、+=，算术操作符+、%，逻辑操作符&、&，位操作符、.前后不加空格；11) if、for、while、switch等关键字与后面的括号间加一个空格；如：4.5 代码行的书写1） 一行代码只做一件事情，如只定义一个变量，或是只写一条语句。2） if、for、while、do等语句各独占一行，执行语句不得紧跟其后，不论执行语句有多少都要加，表明是一个语句块。3） 一对花括号要单独各占一行，但是在do-while、struct和union及其后有“；”的除外，要在一行。如：DoProgramcode;while ( i0 );4.6 变量初始化变量的定义在与函数文件同名的.h文件中，不建议在定义变量的时候顺便初始化，在功能函数模块中专门定义一个初始化函数，初始化系统的各个参数、变量等。4.7 多状态功能程序的编写某些特定的产品会遇到多状态的问题，不同状态编号会有不同的功能需要。这个时候应采用条件编译#ifdef。如：#defined HighCurrentProtect.;Void main();#ifdef HighCurrentProtectFunctionname();#endif5、 编程记录笔记记录程序编写过程中的主要的算法、方案实现过程。主要包含如下部分：1） 工程名称2） 功能模块描述3） 所用算法描述4） 软件流程图5）调试故障分析三、软件测试1、编写过程中的测试在程序编写过程中，依据控制对象的复杂程度，基本上每实现一个或是相关的若干功能模块后做一次测试，切忌在系统完成前一次测试都不做。以实现功能为主要目的，如发现问题及时做出修改。依据实际对象的不同，选择性的以组合若干功能模块或是全系统调试的方式做组合测试，发现并解决系统软件中的不足。由于方案评估时的认识不足，程序编写过程中往往会出现重