1、1 编程规范简述现代高新科技的发展，使得从事电子设计、软件设计等 IT 行业的工程师不单单要具备有良好的专业技术知识，还要具备良好的团队合作能力与协调能力；直观地说，团队合作已经是目前高新技术产业对人员素质的基本要求之一。从表面上看，团队的合作表现在日常的共同完成一个项目的各人之间、各小团队之间的协作行为、协调动作上；但对于个体的工程师而言，其实还会体现在其所负责的工作的细节当中，比如文档、代码的规范化、设计的可重用性等。个体的工程师在工作当中的规范化的修养是最基础的，也是最普遍的工作能力体现；直接或间接影响着团队内部、团队之间甚至行业范围内的横向协作发展，以及纵向的进阶升级发展。这里将介绍一
2、些编程规范的概念及内容，供读者参考；当然，所介绍的大部分规范是大家在长期的工作中所形成的共识，不论他们在哪个国家，哪一个公司，从事哪种行业，只要进行着程序的编写工作，大家都会认同并遵循这些规范。1.1 目的为了统一同学们的程序代码编程规范，提高程序的可读性，利于各人代码的交流，编写此编程规范，并进一步提出编程风格建议，减少程序出错率，提高效率；希望同学们可以养成良好的习惯。1.2 工程结构一个工程一般都由主程序文件作为主程序入口，命名为 main.asm 或 main.c。程序中用到的端口寄存器应在文件开头做出定义，或者 include 统一的外部定义文件。对于综合应用类程序，建议每个功能模块
3、各自放在一个程序文件中，根据程序实现的功能来命名，如 Flash.asm, Key.asm。此外，要为这些程序模块创建函数声明头文件(.inc 和.h)，建议与程序文件同名，供主程序文件包含。用户可配置的内容（如 IO 端口配置）可以放在程序文件开头，也可建立专门的头文件（可命名为?_cfg.inc 或?_cfg.h） 。工程中所有包含的头文件和库文件都要在工程路径下，头文件要添加到 IDE 的 Head files 下。工程文件夹下不要有与工程不相关的程序文件。1.3 命名方式函数、变量、标号等的命名不宜过长，最好在 15 字符以内；以“容易读懂”为原则，建议格式为：前缀+ _ + 行为描述
4、。前缀：用来识别该项位址空间的作用与意义，均以大写字母表示，建议的命名如下表符 号 描 述? 局部标号定义（Local Label）C 常量(Constant), 如: C_PI=3.1416F 汇编函数(Function)P 端口（系统寄存器）T 表（Table,one dimension array）G 全局变量（Global Variable ）对于普通变量，可以不加前缀。如果加前缀则在工程中要统一，建议的变量前缀：前缀 类型 例子P or ptr pointerstr char* or stringa Array aPointch Char chTest,chTempuc unsign
5、ed char ucTest,ucTempi Int iTest,iTempui unsigned int uiTest,uiTempl Long lTest,lTempul unsigned long ulTest,ulTempf float fTest,fResultd double dTest,dResult行为描述：说明该项地址空间的功能、行为或要操作的对象。用表达意思明确的单词来组合，每个单词的第一个字母要大写，表示独立内容的首字母组合也要大写，其余小写，单词之间可以使用“_”来做连接。如：L_MainControlModeT_ScheduleDisplayTypeF_CH0Spee
6、chPlayMode1.4 注释1.4.1 项目头注释（在主程序的开头 Main Program）在 main.c 或 main.asm 开头，注释内容包括: 版权申明 + 项目重点说明项目重点说明包含作者名称、版本、时间、用途、应用芯片、参考资料、维护记录等建议的项目重点说明如下/=/ 工程名称： FlashRW/ 功能描述： 试验指导书第二章/ 内部 flash 的擦除和读写/ A 口低 8 位接 8 个 LED，当读写擦除全部成功时，点亮所有的 LED/ 擦除失败时点亮第一个 LED/ 写单字失败时点亮第二个 LED/ 写页失败时点亮第三个 LED/ 涉及的库： CMacro.lib/
7、SacmV26e.lib/ 组成文件： main.c/ Flash.asm, hardware.asm / hardware.h, hardware.inc/ 硬件连接： / 维护记录： 2002-5-22 v1.0/ 2002-5-23 v1.1/=1.4.2 文件/函数头注释文件开始的地方应加上注释，建议的模块头注释如下/=/ 文件名称： flash.asm/ 功能描述： 擦除、写 1 字、写多字子程序 / 维护记录： 2000-12-5v1.0/=函数开始的地方应加上注释，建议的汇编函数头注释如下/=/ 汇编格式： F_FlashWrite1Word/ C 格式： void FlashW
8、rite1Word (unsigned int * sectorAddress);/ 实现功能： 写一个字到 FLASH 中/ 入口参数： r1 - 被写数据的存储地址/ r2 - 被写数据/ 出口参数： 无/ 破坏寄存器： 无/=建议的 C 函数头注释如下/=/ 语法格式： void FlashErase(unsigned int * sectorAddress);/ 实现功能： 擦除一页 flash/ 参数： SectorAddress - 要擦除页的地址/ 返回值： 无/=1.4.3 变量的注释对于比较重要的变量，可在变量的右边加上注释（可以多行） ，来说明它的作用。如果是以 bit 来
9、定义不同功能时，建议采用以下风格：unsigned int uiSpeedControl;/*/ Bit 7: / Bit 6: +- switch1 for 8-speed control/ Bit 5: / 000 speed level0, stop / 001 speed level1 / 111 speed level7, high speed/ Bit 4: =- reserved/ Bit 3: =- reserved/ Bit 2: / Bit 1: / - switch 4-speed control/ Bit 0: =- reserve/*/1.4.4 行注释对于比较难以理
10、解或重要的行要做注释，说明它的作用。 （在该行的右边，如果比较长可以加入多行） 。1.5 书写外观与缩进1.5.1 大小写汇编指令、寄存器一律用小写书写；宏指令（伪指令）一律用大写书写：.CODEr1 = 0x1000irq on1.5.2 缩进原则程序缩进一律用 TAB。缩进原则为，只要是标号、预处理语句、全局数据、函数说明从 0th TAB。其余的像代码、注释等的缩进，只要前后一致就可以了。对于汇编程序，建议使用下面的缩进方法：F_Function:r1 = 5?Loop:r1 -= 1Jnz ?Loopretf对于 C 程序，建议使用下面的缩进方法：Function()if()switch(i)case 0:i = 1;break;case 1:i = 1;break;default:break;1.5.3 空行的使用相对独立的程序块之间必须加空行。可加一行或多行，以示之间关系的密切程度。源程序中关系较为紧密的代码应尽可能相邻，便于程序阅读和查找。
