转自：http://www.cnblogs.com/hustlzp/archive/2011/03/05/1970936.html
为单片机编写C51代码，程序的可行性当然是必须保证的。但是包括笔者在内的很多新手，都忽略了程序的另一面——可读性、可维护性以及可扩展性。只要稍微有些嵌入式开发经验的读者，若看到笔者在“Zigbee之旅”系列博文中的源码，可能都会从其代码编写习惯中得出一个结论——“菜鸟”。呵呵，笔者决定抽时间学习一下C51嵌入式开发的编程规范，于是在网上收集了一些资料，结合自己的经验，一并分享如下。
一、注释
（1）文件注释
这里说的文件，一般是 .h 和 .c 文件。
/* **********************************************************文件名称： hal.h作 者： hustlzp日 期： 2011/3/5版 本： 1.1功能说明： 硬件抽象层函数列表： （略）修改记录：********************************************************** */
其实一个人学习的话，诸如“文件名称”、“作者”、“版本”、“日期”这些内容，不是特别必要。上述的规范一般在公司内要求比较严格（在多人作业的情况下，对于软件开发的流程控制非常重要）。
但“说明”和“函数列表”这两项，我想还是方便的话写写比较好。当你对这个项目比较淡忘的时候，你只需要扫一下文件头部注释，就能一下子知道这个文件到底是干什么的，明白都有哪些函数。
（2）函数注释
如果对上述的文件注释不怎么感冒的话，我想大家函数注释都应比较熟悉。博客园的园友中大多都是使用vs的，相信vs中对函数注释的支持一定不会忘记（敲三个///，啥都出来了，只需要一个个填就行）。虽然嵌入式开发IDE没有如此强大的功能，但是还是很有必要对“函数功能”、“入口参数”、“出口参数”进行说明：
/* ********************************************************** 函数名称： SetTimer1Period 函数功能： 设置定时器1的定时时长 入口参数： DWORD period定时时长 出口参数： WORD确定PWM脉冲宽度********************************************************** */WORD halSetTimer1Period(DWORD period);
（3）代码注释
至于函数内部的代码注释，需要注意几点：
- 同一函数内的注释最好左对齐
- 少量注释放在代码右边，较多则放在正上方
- 在代码的功能层次上注释，逻辑结构分明
void setSleepTimer(unsigned int sec){unsigned long sleepTimer = 0 ;sleepTimer |= ST0; // 取得目前的睡眠定时器的计数值sleepTimer |= (unsigned long)ST1 << 8;sleepTimer |= (unsigned long)ST2 << 16;sleepTimer += ((unsigned long)sec * 32768); //加上所需要的定时时长ST2 = (unsigned char)(sleepTimer >> 16); // 设置睡眠定时器的比较值ST1 = (unsigned char)(sleepTimer >> 8);ST0 = (unsigned char)sleepTimer;}
二、命名
（1）要具有明确含义
这一点我想不用多说，相信稍具经验的C#程序员都已熟练掌握：
- 尽量使用完整的英文单词，不会的查灵格斯，no拼音
- 可使用一些大家公认的缩写，若使用自定义的缩写，需注释说明
- 函数的命名一般选择动宾短语，即动词+宾语，这样做可较好地说明函数的功能
（2）命名风格的选择
C51编程中，一般会有两种用得较多的命名风格：
大小写风格：
unsigned char get_value();{...}
下划线风格：
unsigned char getValue(){... }
其实选用何种风格并不重要，重要的是坚持在整个项目代码中统一风格，尽量避免混用。
（3）宏及常数的命名
宏及常数的命名必须全用大写字母，而且词与词之间用下划线分隔：
#define GRADIENT 0.03114 #define OFFSET -303 #define ADC14_TO_CELSIUS(ADC_VALUE) (( float )ADC_VALUE * ( float )GRADIENT + OFFSET)
三、排版
（1）缩进
- 在花括号内{}的代码，都应相对于花括号做出一定的缩进
void LCD_write_english_string(unsigned char X,unsigned char Y, char * s) { unsigned char i = 0 ; LCD_set_XY( 0 ,Y); for (i = 0 ;i < 84 ;i ++ ) { LCD_write_byte( 0 , 1 ); } LCD_set_XY(X,Y); while ( * s) { LCD_write_char( * s); s ++ ; i ++ ; if (i >= 14 ) return ; } }
-
充分利用IDE的缩进功能
-
手动缩进时，建时议使用空格键，而不使用 Tab 键，以免用不同的编辑器阅读程序时，因 Tab 键所设置的空格数目不同而造成程序布局的不整齐
（2）空格
- 定义变量时的逗号，只在后面加空格
int a, b, c;
- 比较操作符 , 赋值操作符 "=" 、"+=" ，算术操作符 "+" 、"%" ，逻辑操作符 "&&" 、"&" ，位域操作符 "<<" 、 "^" 等双目操作符的前后建议加空格
a = b + c; a *= 2 ; a = b ^ 2 ;
（3）行
- 一行只写一句代码
- 过长的表达式（超过80个字符）要分成多行书写，在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进适当的缩进，使排版整齐，语句可读。对齐建议使用空格键，不使用 Tab 键，以免用不同的编辑器阅读程序时，因 Tab 键所设置的空格数目不同而造成程序布局混乱：
report_or_not_flag = ((taskno < MAX_ACT_TASK_NUMBER)&& (n7stat_stat_item_valid (stat_item)) && (act_task_table[taskno].result_data != 0));
- 函数中参数较长，则以“，”进行适当的分行
stateCompare(state_object, act_task_table[taskno].stat_object), sizeof (STAT_OBJECT));
- 函数中相对独立的程序块之间，建议加空行
if ( ! valid_ni(ni)) { ... // program code }repssn_ind = ssn_data[index].repssn; repssn_ni = ssn_data[index].ni;
四、宏定义
（1）定义片内/片外资源
对片内资源的定义就不多说了，看一下 ioCC2430.h 就知道了~
还可定义一些片外资源，例如，定义接在P0端口的LED灯：
#define led1 P1_0 #define led2 P1_1 #define led3 P1_2 #define led4 P1_3
（2）定义有意义的常数
有具体意义的常数应在宏中定义，以便日后集中修改：
#define GRADIENT 0.03114 #define OFFSET -303
（3）定义控制参数
在“Zigbee之旅”系列博文中，经常出现需要对某一SFR进行赋值以达到控制的目的，我之前的处理方法是，直接用一个具体的数去赋值，如下所示：
/* UART0通信初始化 ------------------------------------------------------------------ */ void Uart0Init(unsigned char StopBits,unsigned char Parity) { P0SEL |= 0x0C ; // 初始化UART0端口，设置P0.2与P0.3为外部设备IO口 PERCFG &= ~ 0x01 ; // 选择UART0为可选位置一,即RXD接P0.2,TXD接P0.3 U0CSR = 0xC0 ; // 设置为UART模式,并使能接受器 U0GCR = 11 ; U0BAUD = 216 ; // 设置UART0波特率为115200bps U0UCR |= StopBits | Parity; // 设置停止位与奇偶校验 }/* 主函数 ------------------------------------------------------------------ */ void main( void ) { ... Uart0Init( 0x00 , 0x00 ); // 初始化UART0，设置1个停止位，无奇偶校验 ... }
在上面的代码中，首先定义了一个初始化串口的函数 Uart0Unit。然后在 main 函数中使用它，参数分别为0x00（一个停止位），0x00（无奇偶校验）。
这样做的确可以图一时的方便，但是会造成较差的可读性：假如另外一个不太懂CC2430的SFR具体用法的程序员来修改你的代码，他怎么知道这0x00有着什么含义？
为了解决这个问题，我们建议的处理方法是：将可能的选项值全部用宏定义，如下：
// 停止位的设置 #define TWO_STOP_BITS 0x04 #define ONE_STOP_BITS 0x00// 奇偶校验的使能 #define PARITY_ENABLE 0x08 #define PARITY_DISABLE 0x00
OK，下面我们来使用这些宏作为函数 Uart0Unit 的参数：
void main( void ) { ... Uart0Unit(ONE_STOP_BITS, PARITY_DISABLE); ... }
当别人看到这样的代码时，就会瞬间明白：一位停止位、无奇偶校验。修改起来也大为方便了，只需去查找宏定义就OK~
（4）定义一些常用的、功能单一的、有具体意义的代码组合
-
常用的代码组合，如一些赋值、配置/初始化系统资源等代码，都可用宏来定义，如下：
// 设置电源模式 #define SET_POWER_MODE(mode) \ do { \ SLEEP &= ~ 0x03 ; \ SLEEP |= mode; \ PCON |= 0x01 ; \ } while ( 0 )
//将某16位变量的值分别赋给两个8位变量#define SET_WORD(regH, regL, word) do { \ (regH) = HIBYTE( word ); \ (regL) = LOBYTE( word ); \ } while ( 0)
使用的时候，直接将其当做一般的函数调用就行。
CC2430 小贴士
（1）do{...}while(0)
看到这里，很多读者朋友可能对宏定义中的 do{...}while(0) 语句不太理解：既然是while(0)，那么去掉do{...}while(0)，程序也应该是对的呀？为什么还留着呢？
其实，应用这种看似无用的do/while将代码框起来，是为了提高代码的健壮性，减少编译时可能产生的错误，具体可以参考此处。
（2）反斜杠
细心的读者还会发现，在多行宏定义中，除最后一行外每一行都有一个反斜杠 "/"，这有啥用呢？
在宏定义中，规定必须在一行内完成，但是用一行的话会大大降低代码的可读性。于是，我们可以加一个 "/" 表示续行的意思。当然，最后一行不能加。
五、程序结构
（1）根据功能模块划分文件
一个项目，最好按功能分成几个逻辑清晰的模块，每一个模块还可以由一到多个职责各不相同的 .c 源文件来实现。这样一来可降低模块间的耦合性，提高可读性与维护性。
此时，我们可以为每一个模块内的 .c 文件建立共同的 .h 头文件，然后再用一个 total.h 文件引用之前各模块的头文件。以后需引用时，只需引入 total.h 即可。
例如，我们打算实施一个“温度采集系统”，则可以按下面的流程进行：
- 将项目分为三大模块：LCD（屏显）、HAL（硬件抽象）、RF（无线收发）
- 建立三个模块对应的头文件：LCD.h、HAL.h、RF.h
- 建立total.h文件，引用LCD.h、HAL.h、RF.h
- 然后建立3个模块对应的的 .c 源文件
- 在含有main函数的.c文件中，通过引用 total.h 来使用各模块中的代码，实现系统功能
（2）头文件结构
.h头文件的结构顺序一般为：
头文件引入(include) → 宏定义(define) → 函数签名
如下所示：
/* ****************************************************************************** Filename: lcd.h Target: cc2430 Author: KJA Revised: 16/12-2005 Revision: 1.0 Description: Function declarations for common LCD functions for use with the SmartRF04EB. All functions defined here are implemented in lcd.c. ***************************************************************************** */#include " total.h "#define LINE_SIZE 14 // Line length of LCD#define LINE1_ADDR 0x80 // Upper line of LCD #define LINE2_ADDR 0xC0 // Lower line of LCD//symbol codes #define ARROW_LEFT 124 #define ARROW_RIGHT 125 #define ARROW_UP 126 #define ARROW_DOWN 127 //Setup I/O, configure display and clear LCD. void initLcd(void);// Converts the two text strings from ASCII to the character void lcdUpdate( char * pLine1, char * pLine2);// Write one line of text to LCD. void lcdUpdateLine(UINT8 line, char * line_p);// Write a single character to LCD. void lcdUpdateChar(UINT8 line, UINT8 position, char c);
六、结语
OK，C51编码规范的学习到此稍稍停一下，关键还是要在编码实践中去遵循，以后我也会回过头来逐步修改完善本篇日志的。
由于笔者的编码经验还很不足，所以以上内容仅供参考啦，不妥之处还请大家多多批评指正！
5246
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
