軟件編程規范
為了提高源程序的質量和可維護性，從而最終提高軟件產品生產力，特編寫此規范。
本標準規定了程序設計人員進行程序設計時必須遵循的規范。本規范主要針對單片機編程語言和08編譯器而言，包括排版、注釋、命名、變量使用、代碼可測性、程序效率、質量保證等內容。
1.基本規則
格式清晰
注釋簡明扼要
命名規范易懂
函數模塊化
程序易讀易維護
功能準確實現
代碼空間效率和時間效率高
適度的可擴展性
2.單片機編程規范－標識符命名
2.1 命名基本原則
命名要清晰明了，有明確含義，使用完整單詞或約定俗成的縮寫。通常，較短的單詞可通過去掉元音字母形成縮寫；較長的單詞可取單詞的頭幾個字母形成縮寫。即"見名知意"。
命名風格要自始至終保持一致。
命名中若使用特殊約定或縮寫，要有注釋說明。
同一軟件產品內模塊之間接口部分的標識符名稱之前加上模塊標識。
2.2 宏和常量命名
宏和常量用全部大寫字母來命名，詞與詞之間用下劃線分隔。對程序中用到的數字均應用有意義的枚舉或宏來代替。
2.3 變量命名
變量名用小寫字母命名，每個詞的第一個字母大寫。類型前綴（u8\s8 etc.）全局變量另加前綴g_。
局部變量應簡明扼要。局部循環體控制變量優先使用i、j、k等；局部長度變量優先使用len、num等；臨時中間變量優先使用temp、tmp等。
2.4 函數命名
函數名用小寫字母命名，每個詞的第一個字母大寫，并將模塊標識加在最前面。
2.5 文件命名
一個文件包含一類功能或一個模塊的所有函數，文件名稱應清楚表明其功能或性質。
每個.c文件應該有一個同名的.h文件作為頭文件。
3.單片機編程規范－注釋
3.1 注釋基本原則
有助于對程序的閱讀理解，說明程序在"做什么"，解釋代碼的目的、功能和采用的方法。
一般情況源程序有效注釋量在30％左右。
注釋語言必須準確、易懂、簡潔。
邊寫代碼邊注釋，修改代碼同時修改相應的注釋，不再有用的注釋要刪除。
匯編和C中都用"http://"，取消";" 不使用段注釋" /* */ "（調試時可用）
3.2 文件注釋
文件注釋必須說明文件名、函數功能、創建人、創建日期、版本信息等相關信息。
修改文件代碼時，應在文件注釋中記錄修改日期、修改人員，并簡要說明此次修改的目的。所有修改記錄必須保持完整。
文件注釋放在文件頂端，用"/*……*/"格式包含。
注釋文本每行縮進4個空格；每個注釋文本分項名稱應對齊。
/***********************************************************
文件名稱：
作 者：
版 本：
說 明：
修改記錄：
***********************************************************/
3.3 函數注釋
3.3.1 函數頭部注釋
函數頭部注釋應包括函數名稱、函數功能、入口參數、出口參數等內容。如有必要還可增加作者、創建日期、修改記錄（備注）等相關項目。
函數頭部注釋放在每個函數的頂端，用"/*……*/"的格式包含。其中函數名稱應簡寫為FunctionName()，不加入、出口參數等信息。
/***********************************************************
函數名稱：
函數功能：
入口參數：
出口參數：
備 注：
***********************************************************/
3.3.2 代碼注釋
代碼注釋應與被注釋的代碼緊鄰，放在其上方或右方，不可放在下面。如放于上方則需與其上面的代碼用空行隔開。一般少量注釋應該添加在被注釋語句的行尾，一個函數內的多個注釋左對齊；較多注釋則應加在上方且注釋行與被注釋的語句左對齊。
函數代碼注釋用"http://…//"的格式。
通常，分支語句（條件分支、循環語句等）必須編寫注釋。其程序塊結束行"｝"的右方應加表明該程序塊結束的標記"end of ……", 尤其在多重嵌套時。
3.4 變量、常量、宏的注釋
同一類型的標識符應集中定義，并在定義之前一行對其共性加以統一注釋。對單個標識符的注釋加在定義語句的行尾。
全局變量一定要有詳細的注釋，包括其功能、取值范圍、哪些函數或過程存取它以及存取時的注意事項等。
注釋用"http://…//"的格式。
4.單片機編程規范－函數
4.1 設計原則
函數的基本要求：
1）封裝性
正確性：程序要實現設計要求的功能。
穩定性和安全性：程序運行穩定、可靠、安全。
可測試性：程序便于測試和評價。
規范／可讀性：程序書寫風格、命名規則等符合規范。
擴展性：代碼為下一次升級擴展留有空間和接口。
全局效率：軟件系統的整體效率高。
局部效率：某個模塊／子模塊/函數的本身效率高。
編制函數的基本原則：
單個函數的規模盡量限制在200行以內（不包括注釋和空行）。一個函數只完成一個功能。
函數局部變量的數目一般不超過5～10個。
函數內部局部變量定義區和功能實現區（包含變量初始化）之間空一行。
函數名應準確描述函數的功能。通常使用動賓詞組為執行某操作的函數命名。
函數的返回值要清楚明了，尤其是出錯返回值的意義要準確無誤。
不要把與函數返回值類型不同的變量，以編譯系統默認的轉換方式或強制的轉換方式作為返回值返回。
減少函數本身或函數間的遞歸調用。
盡量不要將函數的參數作為工作變量。
4.2 函數定義
函數若沒有入口參數或者出口參數，應用void明確申明。
函數名稱與出口參數類型定義間應該空一格且只空一格。
函數名稱與括號()之間無空格。
函數形參必須給出明確的類型定義。
多個形參的函數，后一個形參與前一個形參的逗號分割符之間添加一個空格。
函數體的前后花括號"｛｝" 各獨占一行。
4.3 局部變量定義
同一行內不要定義過多變量。
同一類的變量在同一行內定義，或者在相鄰行定義。
先定義data型變量，再定義idtata型變量，再定義xdata型變量.（？）
數組、指針等復雜類型的定義放在定義區的最后。
變量定義區不做較復雜的變量賦值。
4.4 功能實現區規范
一行只寫一條語句。
注意運算符的優先級，并用括號明確表達式的操作順序，避免使用默認優先級。
各程序段之間使用一個空行分隔，加以必要的注釋。程序段指能完一個較具體的功能的一行或多行代碼。程序段內的各行代碼之間相互依賴性較強。(1、2、3方式)
不要使用難懂的技巧性很高的語句。
源程序中關系較為緊密的代碼應盡可能相鄰。
完成簡單功能、關系非常密切的一條或幾條語句可編寫為函數或定義為宏。
5.單片機編程規范－排版
5.1 縮進
代碼的每一級均往右縮進4個空格的位置。
不使用Tab鍵
5.2 分行
每行語句（？？？？？超過80個字符）要分成多行書寫；長表達式要在低優先級操作符處劃分新行，操作符放在新行之首，劃分出的新行要進適當的縮進，使排版整齊，語句可讀。避免把注釋插入分行中。
5.3 空行
文件注釋區、頭文件引用區、函數間應該有且只有一行空行。
相鄰函數之間應該有且只有一行空行。
函數體內相對獨立的程序塊之間可以用一行空行或注釋來分隔。
函數注釋和對應的函數體之間不應該有空行。
文件末尾有且只有一行空行。
5.4 空格
函數語句尾部或者注釋之后不能有空格。
括號內側（即左括號后面和右括號前面）不加空格，多重括號間不加空格。
函數形參之間應該有且只有一個空格（形參逗號后面加空格）。
同一行中定義的多個變量間應該有且只有一個空格（變量逗號后面加空格）。
表達式中，若有多個操作符連寫的情況，應使用空格對它們分隔：
在兩個以上的關鍵字、變量、常量進行對等操作時，它們之間的操作符前后均加一個空格；在兩個以上的關鍵字、變量、常量進行非對等操作時，其前后均不應加空格；
逗號只在后面加空格；
雙目操作符，如比較操作符, 賦值操作符"="、"+="，算術操作符"+"、"%"，邏輯操作符"&&"、"&"，位操作符"<<"、"^"等，前后均加一個空格；
單目操作符，如"!"、"~"、"++"、"-"、"&"（地址運算符）等，前后不加空格；
"->"、"."前后不加空格；
if、for、while、switch等關鍵字與后面的括號間加一個空格；
5.5 花括號
if、else if、else、for、while語句無論其執行體是一條語句還是多條語句都必須加花括號，且左右花括號各獨占一行。
do{}while()結構中，"do"和"{"均各占一行，"}"和"while();"共同占用一行。
if ( ) do
{ {
} }while( );
else
{
}
嵌套越少越好，{}不準超過3層
5.6 switch語句
每個case和其判據條件獨占一行。
每個case程序塊需用break結束。特殊情況下需要從一個case塊順序執行到下一個case塊的時候除外，但需要花括號在交界處明確注釋如此操作的原因，以防止出錯。
case程序塊之間空一行，且只空一行。
每個case程序塊的執行語句保持4個空格的縮進。
一般情況下都應該包含default分支。
Switch ( )
{
case x:
break;
case x:
break;
default:
break;
}
6.單片機編程規范－程序結構
6.1 基本要求
有main()函數的.c文件應將main()放在最前面，并明確用void聲明參數和返回值。
對由多個.c文件組成的模塊程序或完整監控程序，建立公共引用頭文件，將需要引用的庫頭文件、標準寄存器定義頭文件、自定義的頭文件、全局變量等均包含在內，供每個文件引用。通常，標準函數庫頭文件采用尖角號< >標志文件名，自定義頭文件采用雙撇號″″標志文件名。
每個.c文件有一個對應的.h文件，.c文件的注釋之后首先定義一個唯一的文件標志宏，并在對應的.h文件中解析該標志。
在.c文件中：
#define FILE_FLAG
在.h文件中：
#ifdef FILE_FLAG
#define XXX
#else
#define XXX extern
#endif
對于確定只被某個.c文件調用的定義可以單獨列在一個頭文件中、單獨調用。
6.2 可重入函數
可重入函數中若使用了全局變量，應通過關中斷、信號量等操作手段對其加以保護。
6.3 函數的形參
由函數調用者負責檢查形參的合法性。
盡量避免將形參作為工作變量使用。
6.4 循環
盡量減少循環嵌套層數
在多重循環中，應將最忙的循環放在最內層
循環體內工作量最小
盡量避免循環體內含有判斷語句
7.工程中所包含的文件
7.1 頭文件
7.1.1 頭文件的形式
MCU程序中的頭文件包括面向硬件對象頭文件、公共頭文件和總頭文件。
MCU C工程編程是面向硬件對象的。例如，要用MCU控制電機(Motor)，在這樣一個系統中，“面向硬件對象”概念體現在，工程中會創建“Motor.c”的源程序文件專門用于電機控制。相應的，也要創建一個同名頭文件“Motor.h”,用于控制電機的MCU引腳定義、相關宏定義和電機控制函數聲明等。像這樣的頭文件，就是面向硬件對象頭文件。與之同名的“*.c”文件可以包含它，來完成控制此硬件對象的MCU引腳定義和相關宏定義；調用該硬件對象控制函數的文件也可以通過調用它來進行函數聲明。
還有一類頭文件不是專門針對于特定的硬件對象的，而是有一定的通用性。這類頭文件被稱為公共頭文件。如工程中包含的“Type.h”文件，該文件用于C語言中類型的別名定義，用戶還可以根據自己的需要，隨時在該文件中添加條目。在工程的任一文件中，需要用到這些別名時，都要包含“Type.h”。可見公共頭文件并不拘泥于具體的硬件對象，它是為整個工程的和諧運作而建立的。
總頭文件(includes.h)是一個較特殊的頭文件。它只被主函數文件包含，用于包含主函數文件中需要的頭文件，宏定義，函數聲明等。它使得主函數文件能夠盡量避免改動，結構更加清晰。
7.1.2 頭文件的命名
總的來說頭文件的命名應盡量做到簡短易懂，見名知意。
面向硬件對象頭文件的名稱一定要與相應的硬件對象驅動文件同名。例？？？
公共頭文件，如果對應于相應的源程序文件而建立，必須與之同名。如，“GeneralFun.c”
是工程中的通用函數定義文件，（像內存數據移動函數，延時函數都屬于通用函數），其他文件在用到這些函數之前，必須進行函數原型聲明，從而建立與之同名的“GeneralFun.h”文件，專門用于相應的函數聲明。其它的公共頭文件沒有同名要求，只要表清文件含義即可，如“Type.h”,“GP32C.h”等。
總頭文件在一個工程中只有一個，它的名稱較為固定，一般取為“Includes.h”
7.1.3 頭文件注意事項
為了防止重復定義需要使用偽指令 #ifndef VarType ……
例：
#ifndef VarType
#define VarType
typedef unsigned char INT8U; //無符號8位數
typedef signed char INT8S; //有符號8位數
typedef unsigned int INT16U; //無符號16位數
typedef signed int INT16S; //有符號16位數
typedef unsigned long INT32U; //無符號32位數
typedef signed long INT32S; //有符號32位數
typedef float FP32; //單精度浮點數
typedef double FP64; //雙精度浮點數
#endif
對于一個項目中的頭文件與芯片相關的寄存器映像文件不可擅自改動，如果的確存在需要改動的地方另外開辟頭文件。
typedef和#define的用法
① typedef的用法
在C/C++語言中，typedef常用來定義一個標識符及關鍵字的別名，它是語言編譯過程的一部分，但它并不實際分配內存空間，實例像：
typedef int INT;
typedef int ARRAY[10];
typedef (int*) pINT;
typedef可以增強程序的可讀性，以及標識符的靈活性，但它也有“非直觀性”等缺點。
② #define的用法
#define為一宏定義語句，通常用它來定義常量(包括無參量與帶參量)，以及用來實現那些“表面似和善、背后一長串”的宏，它本身并不在編譯過程中進行，而是在這之前(預處理過程)就已經完成了，但也因此難以發現潛在的錯誤及其它代碼維護問題，它的實例像：
#define INT int
#define TRUE 1
#define Add(a,b) ((a)+(b));
#define Loop_10 for (int i=0; i<10; i++)
③ typedef與#define的區別
從以上的概念便也能基本清楚，typedef只是為了增加可讀性而為標識符另起的新名稱(僅僅只是個別名)，而#define原本在C中是為了定義常量，到了C++，const、enum、inline的出現使它也漸漸成為了起別名的工具。為了盡可能地兼容，一般都遵循#define定義“可讀”的常量以及一些宏語句的任務，而typedef則常用來定義關鍵字、冗長的類型的別名。
宏定義只是簡單的字符串代換(原地擴展)，而typedef則不是原地擴展，它的新名字具有一定的封裝性，以致于新命名的標識符具有更易定義變量的功能。請看上面第一大點代碼的第三行：
typedef (int*) pINT;
以及下面這行:
#define pINT2 int*
效果相同？實則不同！實踐中見差別：
pINT a,b;的效果同int *a; int *b;
表示定義了兩個整型指針變量。
而pINT2 a,b;的效果同int *a, b;表示定義了一個整型指針變量a和整型變量b。
注意：兩者還有一個行尾;號的區別哦！（？？？）
7.2 源程序文件
源程序文件包括主函數文件、通用函數文件、硬件對象控制文件、芯片初始化文件、中斷向量定義文件和中斷使能文件。
源程序文件的分類和命名類同于頭文件，但也有它自己的特點。
7.2.1 主程序文件
(Main.s 或 Main.c)（?????）
工程中有且僅有一個主程序文件，它包含了工程的主處理流程。
主函數文件中包含：
（1）工程描述
①工程名
工程名中每個意義單詞（或單詞縮寫）的首字母大寫，后綴為.prj。
②硬件連接索引
工程所要控制的硬件對象索引，詳細描述在相應的硬件對象控制文件中給出。
③工程的功能、目的和說明
④注意要點
可以注明編程要點和心得
⑤日期
注明工程完成日期
（2）總頭文件
（3）主函數
如：
//-------------------------------------------------------------------------* //工程文件名:PrgFrame.prj * //硬件連接: * // (1)MCU的I/O口引腳接小燈(見"LED.c"文件說明) * //程序描述:用I/O口控制小燈閃爍 * //目 的:第1個freescale HC08系列MCU C語言程序框架 * //說 明:提供Motorola MCU的編程框架,供教學入門使用 * //注 意:如果延時不夠長的話,會發覺燈不會閃爍,而是一直亮,這是由于人的 * // 視覺的引起的. * //日 期:2006.12.29 * //-------------------《嵌入式技術基礎與實踐》實例--------------------------* #include "Includes.h" //總頭文件 //主函數 void main() { MCUInit(); LEDInit(); //小燈控制引腳初始化 //程序總循環入口 while(1) { LED_L_A('L'); //小燈亮 Delay(10000); //延時 LED_L_A('A'); //小燈暗 Delay(10000); //延時 } } |
7.2.2 芯片初始化文件（“SetUp.c”或 “SetUp.s”）
該文件與具體的芯片型號有關，并且只包含一個芯片初始化函數，若想由編譯器自動調用芯片初始化函數，其函數名必須為"_HC08Setup"，否則編譯器會自動建立并調用一個空的"__HC08Setup"匯編子程序，而不理會用戶創建的芯片初始化函數。為了統一，將該函數起名為"MCUInit",并在主函數中調用該函數。
7.2.3 通用函數頭文件和通用函數文件
通用函數頭文件和通用函數文件，“GenneralFun.h”和“GeneralFun.c”。
//[GenneralFun.h]通用函數頭文件--------------------------------------------- #include"Type.h" //類型別名定義 void Delay(INT16U); //延時函數聲明 |
“GenneralFun.h”中包含：
（1）文件名
（2）通用函數所需用到的頭文件
（3）通用函數用到的宏定義
（4）通用函數聲明
外部函數要用到通用函數時，可包含這個頭文件進行函數聲明。
//[GenneralFun.c]通用函數--------------------------------------------------* //本文件包含: * //(1)Delay:延時函數 * //-------------------------------------------------------------------------* #include "GeneralFun.h" //該頭文件中包含了類型別名定義 //Delay:延時函數-----------------------------------------------------------* //功 能:用程序的方法延時一段時間 * //參 數:k=延時長度(0-65535) * //返 回:無 * //-------------------------------------------------------------------------* void Delay(INT16U k) { INT16U u; for(u=0;u<=k;u++); } |
“GeneralFun.c”中包含：
（1）文件描述：
①文件中的函數的索引
（2）頭文件
通用函數所需頭文件和宏定義可都放在“GeneralFun.h”中，“GeneralFun.c”中只要包含該頭文件即可。
（3）通用函數定義
每個函數前要有相應的函數描述，包括函數名，函數的功能、參數和返回，必要時還可加上函數說明。工程可以根據需要向“GeneralFun.c”文件中添加通用函數，如內存數據移動函數、延時函數這樣的通用函數都可以放入其中。
7.2.4 對象控制文件
對象控制文件以小燈驅動頭文件和小燈驅動文件為例說明。
//[LED.h]小燈驅動頭文件----------------------------------------------------- //小燈控制需要用到的頭文件 #include "GP32C.h" //映像寄存器名定義 #include "Type.h" //類型別名定義 //小燈控制引腳定義 #define Light_P PTA //燈(Light)接在PTA口 #define Light_D DDRA //相應的方向寄存器 #define Light_Pin 1 //燈所在的引腳 //小燈控制相關函數聲明 void LEDInit(void); //定義控制小燈的MCU引腳為輸出 void LED_L_A(INT8U flag); //驅動小燈"亮"、"暗" |
“LED.h”中包含：
（1）文件名
（2）小燈控制所需用到的頭文件
（3）小燈控制引腳定義
（4）小燈控制函數聲明
外部函數要用到小燈控制函數時，可包含這個頭文件進行函數聲明。
//[LED.c]小燈驅動----------------------------------------------------------* //本文件包含: * // (1) LEDInit:定義控制小燈的MCU的I/O引腳為輸出 * // (2) LED_L_A:驅動小燈"亮"、"暗" * //硬件連接: * // (1)本處的小燈是一個發光二極管,由MCU的I/O引腳控制 * // (2)控制引腳=高電平時,小燈"暗";反之,小燈"亮" * //-------------------------------------------------------------------------* #include"LED.h" //該頭文件中包含了小燈控制引腳定義和相關函數聲明 //LEDInit:定義控制小燈的MCU引腳為輸出-------------------------------------* //功能:定義控制小燈的MCU引腳為輸出,并使小燈初始為暗 * //參數：無 * //返回：無 * //-------------------------------------------------------------------------* void LEDInit(void) { Light_D|=1< //令小燈引腳為輸出 Light_P|=1< //初始時，小燈"暗" } //LED_L_A:驅動小燈"亮"、"暗"-----------------------------------------------* //功能:根據flag的值控制小燈的亮和暗 * //參數:flag(flag='A',小燈暗;flag='L',小燈亮) * //返回:無 * //-------------------------------------------------------------------------* void LED_L_A(INT8U flag) { if(flag=='A') Light_P|=1< //小燈"暗" else if(flag=='L') Light_P&=~(1< //小燈"亮" } |
“LED.c”中包含：
（1）文件描述：
①文件中的函數的索引
②硬件對象及其與MCU的連接描述
（2）頭文件
小燈控制所需用到的頭文件和小燈控制引腳定義及小燈控制函數中用到的其他常量聲明可全部已放在“LED.h”中，“LED.c”只要包含該頭文件即可。
（3）小燈驅動函數定義
每個函數前要有相應的函數描述，包括函數名，函數的功能、參數和返回，必要時還可加上函數說明。
7.2.5 中斷處理函數和中斷向量表文件
//[Vectors08.c]中斷處理函數與中斷向量表------------------------------------* //功能： * // (1)定義中斷處理子程序 * // (2)放置中斷向量表 * //說明:該文件與芯片具體型號有關. * // (1)芯片型號MC68HC908GP32 * //-------------------------------------------------------------------------* //此處為用戶中斷處理函數的存放處 //未定義的中斷處理函數,本函數不能刪除 #pragma interrupt_handler isrDummy void isrDummy(void) { } //中斷矢量表，需定義中斷函數，可修改下表中的相應項目 //(interrupt service routine，isr 中斷處理程序) #pragma abs_address:0xffdc //中斷向量表起始地址 void (* const _vectab[])(void) = { isrDummy, //時基中斷 isrDummy, //AD轉換中斷 isrDummy, //鍵盤中斷 isrDummy, //SCI發送中斷 isrDummy, //SCI接收中斷 isrDummy, //SCI錯誤中斷 isrDummy, //SPI發送中斷 isrDummy, //SPI錯誤中斷 isrDummy, //TIM2溢出中斷 isrDummy, //TIM2通道1輸入捕捉/輸出比較中斷 isrDummy, //TIM2通道0輸入捕捉/輸出比較中斷 isrDummy, //TIM1溢出中斷 isrDummy, //TIM1通道1輸入捕捉/輸出比較中斷 isrDummy, //TIM1通道0輸入捕捉/輸出比較中斷 isrDummy, //CGM的PLL鎖相狀態變化中斷 isrDummy, //IRQ引腳中斷 isrDummy //SWI指令中斷 //RESET是特殊中斷,其向量由開發環境直接設置(在本軟件系統的crt08.o文件中) }; #pragma end_abs_address |
該文件與具體的芯片型號有關，可以根據需要向，文件中添加相應的中斷向量和中斷處理函數。
7.3 最小工程文件集
第一個C工程”PrgFrame.prj”給出了Motorola MCU編程框架，同時它也是一個很好的編程規范示例。下面講解C工程編程規范，就以該工程為例。
圖1給出了PrgFrame.prj的最小文件集，由于該工程中只用到復位中斷，且其中斷向量由開發環境直接設置，所以工程中可以不包含中斷向量定義文件“vectors08.c”(實際工程中包含這個文件，是為了確立一個標準的工程框架)。
類型別名定義頭文件(Type.h) 通用函數頭文件(GeneralFun.h) GP32映像寄存器名定義頭文件(GP32C.h) |
注意圖（1）中的源程序文件和頭文件的對應關系： ① GenneralFun.c ßà GenneralFun.h ② LED.c ßà LED.h
|
