單片機開發之C語言編程基本規範

爲了提升源程序的質量和可維護性，從而最終提升軟件產品生產力，特編寫此規範。本標準規定了程序設計人員進行程序設計時必須遵循的規範。本規範主要針對單片機編程語言和08編譯器而言，包括排版、註釋、命名、變量使用、代碼可測性、程序效率、質量保證等內容。 
1．基本規則 
格式清晰、註釋簡明扼要、命名規範易懂、函數模塊化、程序易讀易維護、功能準確實現、代碼空間效率和時間效率高、適度的可擴展性、單片機編程規範－標識符命名 
2．標識符命名 2.1 命名基本原則 
（1）命名清晰明瞭，有明確含義，使用完整單詞或約定俗成的縮寫。一般，較短的單詞可經過去掉元音字母造成縮寫；較長的單詞可取單詞的頭幾個字母造成縮寫。即"見名知意"。（2）命名風格要自始至終保持一致。 
（3）命名中若使用特殊約定或縮寫，要有註釋說明。
（4）同一軟件產品內模塊之間接口部分的標識符名稱以前加上模塊標識。
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中都用"//"，取消";"  不使用段註釋" /*  */ "（調試時可用） 
3.2 文件註釋 
文件註釋必須說明文件名、函數功能、建立人、建立日期、版本信息等相關信息。
修改文件代碼時，應在文件註釋中記錄修改日期、修改人員，並簡要說明這次修改的目的。全部修改記錄必須保持完整。
文件註釋放在文件頂端，用"/*……*/"格式包含。
註釋文本每行縮進4個空格；每一個註釋文本分項名稱應對齊。
/***********************************************************
文件名稱：
做 者：
版 本：
說 明：
修改記錄：
***********************************************************/
3.3 函數註釋 
3.3.1 函數頭部註釋
函數頭部註釋應包括函數名稱、函數功能、入口參數、出口參數等內容。若有必要還可增長做者、建立日期、修改記錄（備註）等相關項目。
函數頭部註釋放在每一個函數的頂端，用"/*……*/"的格式包含。其中函數名稱應簡寫爲Name()，不加入、出口參數等信息。
/***********************************************************
函數名稱：
函數功能：
入口參數：
出口參數：
備 注：
***********************************************************/
3.3.2 代碼註釋
代碼註釋應與被註釋的代碼緊鄰，放在其上方或右方，不可放在下面。如放於上方則需與其上面的代碼用空行隔開。通常少許註釋應該添加在被註釋語句的行尾，一個函數內的多個註釋左對齊；較多註釋則應加在上方且註釋行與被註釋的語句左對齊信盈達嵌入式企鵝要妖氣嗚嗚吧久零就要。
函數代碼註釋用"//…//"的格式。
一般，分支語句（條件分支、循環語句等）必須編寫註釋。其程序塊結束行"｝"的右方應加代表該程序塊結束的標記"end of ……", 尤爲在多重嵌套時。
3.4 變量、常量、宏的註釋 
同一類型的標識符應集中定義，並在定義以前一行對其共性加以統一註釋。對單個標識符的註釋加在定義語句的行尾。
全局變量必定要有詳細的註釋，包括其功能、取值範圍、哪些函數或過程存取它以及存取時的注意事項等。
註釋用"//…//"的格式。 
4．函數 4.1 函數設計原則 
函數的基本要求： 
1）封裝性
1) 正確性：程序要實現設計要求的功能。
2) 穩定性和安全性：程序運行穩定、可靠、安全。
3) 可測試性：程序便於測試和評價。
4) 規範／可讀性：程序書寫風格、命名規則等符合規範。
5) 擴展性：代碼爲下一次升級擴展留有空間和接口。
6) 全局效率：軟件系統的總體效率高。
7) 局部效率：某個模塊／子模塊/函數的自己效率高。
編制函數的基本原則：
1) 單個函數的規模儘可能限制在200行之內（不包括註釋和空行）。一個函數只完成一個功能。
2) 函數局部變量的數目通常不超過5～10個。
3) 函數內部局部變量定義區和功能實現區（包含變量初始化）之間空一行。
4) 函數名應準確描述函數的功能。一般使用動賓詞組爲執行某操做的函數命名。
5) 函數的返回值要清楚明瞭，尤爲是出錯返回值的意義要準確無誤。
6) 不要把與函數返回值類型不一樣的變量，以編譯系統默認的轉換方式或強制的轉換方式做爲返回值返回。
7) 減小函數自己或函數間的遞歸調用。
8) 儘可能不要將函數的參數做爲工做變量。
4.2 函數定義 
1) 函數若沒有入口參數或者出口參數，應用void明確申明。
2) 函數名稱與出口參數類型定義間應該空一格且只空一格。
3) 函數名稱與括號()之間無空格。
4) 函數形參必須給出明確的類型定義。
5) 多個形參的函數，後一個形參與前一個形參的逗號分割符之間添加一個空格。
6) 函數體的先後花括號"｛｝" 各獨佔一行。
4.3 局部變量定義 
1) 同一行內不要定義過多變量。
2) 同一類的變量在同一行內定義，或者在相鄰行定義。
3) 先定義data型變量，再定義idtata型變量，再定義xdata型變量.（？）
4) 數組、指針等複雜類型的定義放在定義區的最後。
5) 變量定義區不作較複雜的變量賦值。
4.4 功能實現區規範 
1) 一行只寫一條語句。
2) 注意運算符的優先級，並用括號明確表達式的操做順序，避免使用默認優先級信盈達嵌入式企鵝要妖氣嗚嗚吧久零就要。
3) 各程序段之間使用一個空行分隔，加以必要的註釋。程序段指能完一個較具體的功能的一行或多行代碼。程序段內的各行代碼之間相互依賴性較強。(一、二、3方式)
4) 不要使用難懂的技巧性很高的語句。
5) 源程序中關係較爲緊密的代碼應儘量相鄰。
6) 完成簡單功能、關係很是密切的一條或幾條語句可編寫爲函數或定義爲宏。 
5． 單片機編程規範－排版 
5.1 縮進 
代碼的每一級均往右縮進4個空格的位置。不使用Tab鍵 
5.2 分行 
每行語句（？？？？？超過80個字符）要分紅多行書寫；長表達式要在低優先級操做符處劃分新行，操做符放在新行之首，劃分出的新行要進適當的縮進，使排版整齊，語句可讀。避免把註釋插入分行中。
5.3 空行 
1) 文件註釋區、頭文件引用區、函數間應該有且只有一行空行。
2) 相鄰函數之間應該有且只有一行空行。
3) 函數體內相對獨立的程序塊之間能夠用一行空行或註釋來分隔。
4) 函數註釋和對應的函數體之間不該該有空行。
5) 文件末尾有且只有一行空行。
5.4 空格 
1) 函數語句尾部或者註釋以後不能有空格。
2) 括號內側（即左括號後面和右括號前面）不加空格，多重括號間不加空格。
3) 函數形參之間應該有且只有一個空格（形參逗號後面加空格）。
4) 同一行中定義的多個變量間應該有且只有一個空格（變量逗號後面加空格）。
5) 表達式中，如有多個操做符連寫的狀況，應使用空格對它們分隔：
6) 在兩個以上的關鍵字、變量、常量進行對等操做時，它們之間的操做符先後均加一個空格；在兩個以上的關鍵字、變量、常量進行非對等操做時，其先後均不該加空格；
7) 逗號只在後面加空格；
8) 雙目操做符，如比較操做符, 賦值操做符"="、"+="，算術操做符"+"、"%"，邏輯操做符"&&"、"&"，位操做符"<<"、"^"等，先後均加一個空格；
9) 單目操做符，如"!"、"~"、"++"、"-"、"&"（地址運算符）等，先後不加空格；
10) "->"、"."先後不加空格；
11) if、for、while、switch等關鍵字與後面的括號間加一個空格；
5.5 花括號 
1)  if、else if、else、for、while語句不管其執行體是一條語句仍是多條語句都必須加花括號，且左右花括號各獨佔一行。
2)  do{}while()結構中，"do"和"{"均各佔一行，"}"和"while();"共同佔用一行。
if ( ) do
{ {
} }while( );
else
{
}
嵌套越少越好，{}不許超過3層  
5.6 switch語句 
1) 每一個case和其判據條件獨佔一行。
2) 每一個case程序塊需用break結束。特殊狀況下須要從一個case塊順序執行到下一個case塊的時候除外，但須要花括號在交界處明確註釋如此操做的緣由，以防止出錯。
3) case程序塊之間空一行，且只空一行。
4) 每一個case程序塊的執行語句保持4個空格的縮進。
5) 通常狀況下都應該包含default分支。
Switch ( )
{
case x:
break;
case x:
break;
default:
break;
}
6．程序結構 6.1 基本要求 
1) 有main()函數的.c文件應將main()放在最前面，並明確用void聲明參數和返回值。
2) 對由多個.c文件組成的模塊程序或完整監控程序，創建公共引用頭文件，將須要引用的庫頭文件、標準寄存器定義頭文件、自定義的頭文件、全局變量等均包含在內，供每一個文件引用。一般，標準函數庫頭文件採用尖角號< >標誌文件名，自定義頭文件採用雙撇號″″標誌文件名。
3) 每一個.c文件有一個對應的.h文件，.c文件的註釋以後首先定義一個惟一的文件標誌宏，並在對應的.h文件中解析該標誌。
在.c文件中：
#define FILE_FLAG
在.h文件中：&
6．程序結構 6.1 基本要求 
1) 有main()函數的.c文件應將main()放在最前面，並明確用void聲明參數和返回值。
2) 對由多個.c文件組成的模塊程序或完整監控程序，創建公共引用頭文件，將須要引用的庫頭文件、標準寄存器定義頭文件、自定義的頭文件、全局變量等均包含在內，供每一個文件引用。一般，標準函數庫頭文件採用尖角號< >標誌文件名，自定義頭文件採用雙撇號″″標誌文件名。
3) 每一個.c文件有一個對應的.h文件，.c文件的註釋以後首先定義一個惟一的文件標誌宏，並在對應的.h文件中解析該標誌。
在.c文件中：
#define FILE_FLAG
在.h文件中：
#ifdef FILE_FLAG
#define XXX
#else
#define XXX extern
#endif
4)  對於肯定只被某個.c文件調用的定義能夠單獨列在一個頭文件中、單獨調用。