1單晶片C51程式設計規範- 前言
  為了提升原始碼的質量和可維護性,從而最終提升軟體產品生產力,特編寫此規範。


2 單晶片C51程式設計規範-範圍
  本標準規定了程式設計人員進行程式設計時必須遵循的規範。本規範主要針對C51程式設計語言和keil編譯器而言,包括排版、註釋、命名、變數使用、程式碼可測性、程式效率、質量保證等內容。


3 單晶片C51程式設計規範-總則
l 格式清晰
l 註釋簡明扼要
l 命名規範易懂
l 函式模組化
l 程式易讀易維護
l 功能準確實現
l 程式碼空間效率和時間效率高
l 適度的可擴展性


4 單晶片C51程式設計規範-數據類型定義
程式設計時統一採用下述新類型名的模式定義數據類型。
建立一個datatype.h文件,在該文件中進行如下定義︰
typedef bit BOOL;               // 位變數 //
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;             // 單精度浮點數(32位長度) //
typedef double FP64;            // 雙精度浮點數(64位長度) //


5 單晶片C51程式設計規範-標識符命名


5.1 命名基本原則
l 命名要清晰明了,有明確含義,使用完整單詞或約定俗成的縮寫。通常,較短的單詞可透過去掉元音字母形成縮寫;較長的單詞可取單詞的頭幾個字母形成縮寫。即"見名知意"。
l 命名風格要自始至終保持一致。
l 命名中若使用特殊約定或縮寫,要有註釋說明。
l 除了編譯開關/頭文件等特殊應用,應避免使用以下劃線開始和/或結尾的定義。
l 同一軟體產品內模組之間界面部分的標識符名稱之前加上模組標識。


5.2 巨集和常量命名
巨集和常量用全部大寫字母來命名,詞與詞之間用下劃線分隔。對程式中用到的數字均應用有意義的枚舉或巨集來代替。


5.3 變數命名
變數名用小寫字母命名,每個詞的第一個字母大寫。類型前綴(u8\s8 etc.)全域變數另加前綴g_。
區域變數應簡明扼要。區域循環體控制變數優先使用i、j、k等;區域長度變數優先使用len、num等;臨時中間變數優先使用temp、tmp等。


5.4 函式命名
函式名用小寫字母命名,每個詞的第一個字母大寫,並將模組標識加在最前面。


5.5 文件命名
一個文件包含一類功能或一個模組的所有函式,文件名稱應清楚表明其功能或性質。
每個.c文件應該有一個同名的.h文件作為頭文件。


6 單晶片C51程式設計規範-註釋


6.1 註釋基本原則
l 有助于對程式的閱讀理解,說明程式在"做什麼",解釋程式碼的目的、功能和採用的方法。
l 一般情況原始碼有效註釋量在30%左右。
l 註釋語言必須準確、易懂、簡潔。
l 邊寫程式碼邊註釋,修改程式碼同時修改相應的註釋,不再有用的註釋要刪除。


6.2 文件註釋
文件註釋必須說明文件名、函式功能、建立人、建立日期、版本訊息等相關訊息。
修改文件程式碼時,應在文件註釋中記錄修改日期、修改人員,並簡要說明此次修改的目的。所有修改記錄必須保持完整。
文件註釋放在文件頂端,用"/*……*/"格式包含。
註釋文本每行縮進4個空格;每個註釋文本分項名稱應對齊。
/***********************************************************
文件名稱︰
作 者︰
版 本︰
說 明︰
修改記錄︰
***********************************************************/


6.3 函式註釋
6.3.1 函式頭部註釋
函式頭部註釋應包括函式名稱、函式功能、入口參數、返回參數等內容。如有必要還可增加作者、建立日期、修改記錄(備注)等相關項目。
函式頭部註釋放在每個函式的頂端,用"/*……*/"的格式包含。其中函式名稱應簡寫為FunctionName(),不加入、返回參數等訊息。
/***********************************************************
函式名稱︰
函式功能︰
入口參數︰
返回參數︰
備 注︰
***********************************************************/


6.3.2 程式碼註釋
程式碼註釋應與被註釋的程式碼緊鄰,放在其上方或右方,不可放在下面。如放于上方則需與其上面的程式碼用空行隔開。一般少量註釋應該添加在被註釋語句的行尾,一個函式內的多個註釋左對齊;較多註釋則應加在上方且註釋行與被註釋的語句左對齊。
函式程式碼註釋用"//…//"的格式。
通常,分支語句(條件分支、循環語句等)必須編寫註釋。其程式塊結束行"}"的右方應加表明該程式塊結束的標記"end of ……", 尤其在多重巢狀時。


6.4 變數、常量、巨集的註釋
同一類型的標識符應集中定義,並在定義之前一行對其共性加以統一註釋。對單個標識符的註釋加在定義語句的行尾。
全域變數一定要有詳細的註釋,包括其功能、取值範圍、哪些函式或過程存取它以及存取時的注意事項等。
註釋用"//…//"的格式。


7 單晶片C51程式設計規範-函式


7.1 設計原則
函式的基本要求︰
l 正確性︰程式要實現設計要求的功能。
l 穩定性和安全性︰程式營運穩定、可靠、安全。
l 可測試性︰程式便于測試和評價。
l 規範/可讀性︰程式書寫風格、命名規則等符合規範。
l 擴展性︰程式碼為下一次升級擴展留有空間和界面。
l 全域效率︰軟體系統的整體效率高。
l 區域效率︰某個模組/子模組/函式的本身效率高。


編製函式的基本原則︰
l 單個函式的規模盡量限制在200行以內(不包括註釋和空行)。一個函式只完成一個功能。
l 函式區域變數的數目一般不超過5~10個。
l 函式內部區域變數定義區和功能實現區(包含變數初始化)之間空一行。
l 函式名應準確描述函式的功能。通常使用動賓詞組為執行某操作的函式命名。
l 函式的返回值要清楚明了,尤其是出錯返回值的意義要準確無誤。
l 不要把與函式返回值類型不同的變數,以編譯系統默認的轉換模式或強製的轉換模式作為返回值返回。
l 減少函式本身或函式間的遞歸呼叫。
l 盡量不要將函式的參數作為工作變數。


7.2 函式定義
l 函式若沒有入口參數或者返回參數,應用void明確申明。
l 函式名稱與返回參數類型定義間應該空一格且只空一格。
l 函式名稱與括號()之間無空格。
l 函式形參必須給出明確的類型定義。
l 多個形參的函式,后一個形參與前一個形參的逗號分割符之間添加一個空格。
l 函式體的前后花括號"{}" 各獨佔一行。


7.3 區域變數定義
l 同一行內不要定義過多變數。
l 同一類的變數在同一行內定義,或者在相鄰行定義。
l 先定義data型變數,再定義idtata型變數,再定義xdata型變數.
l 數組、指針等複雜類型的定義放在定義區的最後。
l 變數定義區不做較複雜的變數賦值。


7.4 功能實現區規範
l 一行只寫一條語句。
l 注意運算符的優先級,並用括號明確表達式的操作順序,避免使用默認優先級。
l 各程式段之間使用一個空行分隔,加以必要的註釋。程式段指能完一個較具體的功能的一行或多行程式碼。程式段內的各行程式碼之間相互倚賴性較強。
l 不要使用難懂的技巧性很高的語句。
l 原始碼中關係較為緊密的程式碼應儘可能相鄰。
l 完成簡單功能、關係非常密切的一條或幾條語句可編寫為函式或定義為巨集。


8 單晶片C51程式設計規範-排版


8.1 縮進
程式碼的每一級均往右縮進4個空格的位置。


8.2 分行
過長的語句(超過80個字符)要分成多行書寫;長表達式要在低優先級操作符處劃分新行,操作符放在新行之首,劃分出的新行要進適當的縮進,使排版整齊,語句可讀。避免把註釋插入分行中。


8.3 空行
l 文件註釋區、頭文件引用區、函式間應該有且只有一行空行。
l 相鄰函式之間應該有且只有一行空行。
l 函式體內相對獨立的程式塊之間可以用一行空行或註釋來分隔。
l 函式註釋和對應的函式體之間不應該有空行。
l 文件末尾有且只有一行空行。


8.4 空格
l 函式語句尾部或者註釋之后不能有空格。
l 括號內側(即左括號后面和右括號前面)不加空格,多重括號間不加空格。
l 函式形參之間應該有且只有一個空格(形參逗號后面加空格)。
l 同一行中定義的多個變數間應該有且只有一個空格(變數逗號后面加空格)。
l 表達式中,若有多個操作符連寫的情況,應使用空格對它們分隔︰
在兩個以上的關鍵字、變數、常量進行對等操作時,它們之間的操作符前后均加一個空格;在兩個以上的關鍵字、變數、常量進行非對等操作時,其前后均不應加空格;
逗號只在后面加空格;
雙目操作符,如比較操作符, 賦值操作符"="、"+=",算術操作符"+"、"%",邏輯操作符" "、" ",位操作符"<<"、"^"等,前后均加一個空格;
單目操作符,如"!"、"~"、"++"、"-"、" "(位址運算符)等,前后不加空格;
"->"、"."前后不加空格;
if、for、while、switch等關鍵字與后面的括號間加一個空格;


8.5 花括號
l if、else if、else、for、while語句無論其執行體是一條語句還是多條語句都必須加花括號,且左右花括號各獨佔一行。
l do{}while()架構中,"do"和"{"均各占一行,"}"和"while();"共同佔用一行。
if ( ) do
{ {


} }while( );
else
{


}


8.6 switch語句
l 每個case和其判據條件獨佔一行。
l 每個case程式塊需用break結束。特殊情況下需要從一個case塊順序執行到下一個case塊的時候除外,但需要在交界處明確註釋如此操作的原因,以防止出錯。
l case程式塊之間空一行,且只空一行。
l 每個case程式塊的執行語句保持4個空格的縮進。
l 一般情況下都應該包含default分支。
Switch ( )
{
case x:


break;


case x:


break;


default:


break;
}


9 單晶片C51程式設計規範-程式架構


9.1 基本要求
l 有main()函式的.c文件應將main()放在最前面,並明確用void聲明參數和返回值。
l 對由多個.c文件組成的模組程式或完整監控程式,建立公共引用頭文件,將需要引用的庫頭文件、標準暫存器定義頭文件、自定義的頭文件、全域變數等均包含在內,供每個文件引用。通常,標準函式庫頭文件採用尖角號< >標誌文件名,自定義頭文件採用雙撇號〃〃標誌文件名。
l 每個.c文件有一個對應的.h文件,.c文件的註釋之后首先定義一個唯一的文件標誌巨集,並在對應的.h文件中解析該標誌。
在.c文件中︰
#define FILE_FLAG
在.h文件中︰
#ifdef FILE_FLAG
#define XXX
#else
#define XXX extern
#endif
l 對于確定只被某個.c文件呼叫的定義可以單獨列在一個頭文件中、單獨呼叫。


9.2 可重入函式
可重入函式中若使用了全域變數,應透過關中斷、信號量等操作手段對其加以保護。


9.3 函式的形參
l 由函式呼叫者負責檢查形參的合法性。
l 盡量避免將形參作為工作變數使用。


9.4 循環
l 盡量減少循環巢狀層數
l 在多重循環中,應將最忙的循環放在最內層
l 循環體內工作量最小
l 盡量避免循環體內含有判斷語句

創作者介紹
創作者 立你斯 的頭像
立你斯

立你斯學習記錄

立你斯 發表在 痞客邦 留言(0) 人氣()