代码规范化.doc

1 编程规范简述
现代高新科技得发展，使得从事电子设计、软件设计等IT行业得工程师不单单要具备有良好得专业技术知识，还要具备良好得团队合作能力与协调能力；直观地说，团队合作已经就是目前高新技术产业对人员素质得基本要求之一。
从表面上瞧，团队得合作表现在日常得共同完成一个项目得各人之间、各小团队之间得协作行为、协调动作上；但对于个体得工程师而言，其实还会体现在其所负责得工作得细节当中，比如文档、代码得规范化、设计得可重用性等。个体得工程师在工作当中得规范化得修养就是最基础得，也就是最普遍得工作能力体现；直接或间接影响着团队内部、团队之间甚至行业范围内得横向协作发展，以及纵向得进阶升级发展。淥鹼漣颛鮐饃鲤。
这里将介绍一些编程规范得概念及内容，供读者参考；当然，所介绍得大部分规范就是大家在长期得工作中所形成得共识，不论她们在哪个国家，哪一个公司，从事哪种行业，只要进行着程序得编写工作，大家都会认同并遵循这些规范。狭务舰鏹塢铷鸱。
1.1 目得
为了统一同学们得程序代码编程规范，提高程序得可读性，利于各人代码得交流，编写此编程规范，并进一步提出编程风格建议，减少程序出错率，提高效率；希望同学们可以养成良好得习惯。启詢约帏锣焘弒。
1.2 工程结构
一个工程一般都由主程序文件作为主程序入口，命名为main、asm或main、c。程序中用到得端口寄存器应在文件开头做出定义，或者include统一得外部定义文件。艰確肅滞擰账狹。
对于综合应用类程序，建议每个功能模块各自放在一个程序文件中，根据程序实现得功能来命名，如Flash、asm, Key、asm。此外，要为这些程序模块创建函数声明头文件(、inc与、h)，建议与程序文件同名，供主程序文件包含。用户可配置得内容（如IO端口配置）可以放在程序文件开头，也可建立专门得头文件（可命名为???_cfg、inc或???_cfg、h）。饮谳呒码榮緶務。
工程中所有包含得头文件与库文件都要在工程路径下，头文件要添加到IDE得Head files下。
工程文件夹下不要有与工程不相关得程序文件。
1.3 命名方式
函数、变量、标号等得命名不宜过长，最好在15字符以内；以“容易读懂”为原则，建议格式为：[前缀]+ ’_’ +行为描述。鮭觀简爱灣双辞。
前缀：用来识别该项位址空间得作用与意义，均以大写字母表示，建议得命名如下表
符 号
描 述
?
局部标号定义（Local Label）
C
常量(Constant), 如: C_PI=3、1416
F
汇编函数(Function)
P
端口（系统寄存器）
T
表（Table,one dimension array）
G
全局变量（Global Variable）
对于普通变量，可以不加前缀。如果加前缀则在工程中要统一，建议得变量前缀：
前缀
类型
例子
P or ptr
pointer

str
char* or string

a
Array
aPoint
ch
Char
chTest,chTemp
uc
unsigned char
ucTest,ucTemp
i
Int
iTest,iTemp
ui
unsigned int
uiTest,uiTemp
l
Long
lTest,lTemp
ul
unsigned long
ulTest,ulTemp
f
float
fTest,fResult
d
double
dTest,dResult
行为描述：说明该项地址空间得功能、行为或要操作得对象。用表达意思明确得单词来组合，每个单词得第一个字母要大写，表示独立内容得首字母组合也要大写，其余小写，单词之间可以使用“_”来做连接。如：慳飒饉缑換鲒繼。
L_MainControlMode
T_ScheduleDisplayType
F_CH0SpeechPlayMode
1.4 注释
1.4.1 项目头注释（在主程序得开头 Main Program）
在main、c或main、asm开头，注释内容包括: 版权申明 + 项目重点说明
项目重点说明包含作者名称、版本、时间、用途、应用芯片、参考资料、维护记录等
建议得项目重点说明如下
//============================================================幂轸懨缀挡壙专。
// 工程名称： FlashRW
// 功能描述： 《试验指导书》第二章
// 内部flash得擦除与读写
// A口低8位接8个LED，当读写擦除全部成功时，点亮所有得LED
// 擦除失败时点亮第一个LED
// 写单字失败时点亮第二个LED
// 写页失败时点亮第三个LED
// 涉及得库： CMacro、lib
// 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-5 v1、0
//======================================================讨腊摳減鹈穑轩。
函数开始得地方应加上注释，建议得汇编函数头注释如下
//======================================================疇鱔荚镔傴鸶韞。
// 汇编格式： F_FlashWrite1Word
// C格式： void FlashWrite1Word (unsigned int * sectorAddress);钐釅瞒竖诈絆烨。
// 实现功能： 写一个字到FLASH中
// 入口参数： r1 - 被写数据得存储地址
// r2 - 被写数据
// 出口参数： 无
// 破坏寄存器： 无
//======================================================闊适烨蛴賒蓮寫。
建议得C函数头注释如下
//=============================================================櫛坜繃髋瑪拥臉。
// 语法格式： void FlashErase(unsigned int * sectorAddress);揚許谒唢攔辐塏。
// 实现功能： 擦除一页flash
// 参数： SectorAddress - 要擦除页得地址
// 返回值： 无
//=============================================================诂灘辎烧焕蕎狭。
1.4.3 变量得注释
对于比较重要得变量，可在变量得右边加上注释（可以多行），来说明它得作用。如果就是以bit来定义不同功能时，建议采用以下风格：驽浊颂罗瀧灃縝。
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 行注释
对于比较难以理解或重要得行要做注释，说明它得作用。（在该行得右边，如果比较长可以加入多行）。
1.5 书写外观与缩进
1.5.1 大小写
汇编指令、寄存器一律用小写书写；宏指令（伪指令）一律用大写书写：
、CODE
r1 = 0x1000
irq on
1.5.2 缩进原则
程序缩进一律用TAB。缩进原则为，只要就是标号、预处理语句、全局数据、函数说明从0th TAB。其余得像代码、注释等得缩进，只要前后一致就可以了。别綁賓钉镦瀋論。
对于汇编程序，建议使用下面得缩进方法：
F_Function:
r1 = 5
?Loop:
r1 -= 1
Jnz ?Loop
retf
对于C程序，建议使用下面得缩进方法：
Function()
{
if(……)
{
switch(i)
{
case 0:
i = 1;
break;
case 1:
i = 1;
break;
default:
break;
}
}
}
1.5.3 空行得使用
相对独立得程序块之间必须加空行。可加一行或多行，以示之间关系得密切程度。源程序中关系较为紧密得代码应尽可能相邻，便于程序阅读与查找。阖賠极异戇軫貓。