單片機(jī)匯編程序編碼規(guī)范

http://www.blogcn.com/u2/94/42/cbz6000/blog/43716860.html

引言
???? 軟件設(shè)計(jì)更多地是一種工程，而不是一種個(gè)人藝術(shù)。如果不統(tǒng)一編程規(guī)范，最終寫(xiě)出的程序，其可讀性將較差，這不僅給代碼的理解帶來(lái)障礙，增加維護(hù)階段的工作量，同時(shí)不規(guī)范的代碼隱含錯(cuò)誤的可能性也比較大。

分析表明，編碼階段產(chǎn)生的錯(cuò)誤當(dāng)中，語(yǔ)法錯(cuò)誤大概占 20% 左右，而由于未嚴(yán)格檢查軟件邏輯導(dǎo)致的錯(cuò)誤、函數(shù)（模塊）之間接口錯(cuò)誤及由于代碼可理解度低導(dǎo)致優(yōu)化維護(hù)階段對(duì)代碼的錯(cuò)誤修改引起的錯(cuò)誤則占了一半以上。

可見(jiàn)，提高軟件質(zhì)量必須降低編碼階段的錯(cuò)誤率。如何有效降低編碼階段的錯(cuò)誤呢？這需要制定詳細(xì)的軟件編程規(guī)范，并培訓(xùn)每一位程序員，最終的結(jié)果可以把編碼階段的錯(cuò)誤降至 10% 左右，同時(shí)也降低了程序的測(cè)試費(fèi)用，效果相當(dāng)顯著。

本文從代碼的可維護(hù)性（可讀性、可理解性、可修改性）、代碼邏輯與效率、函數(shù)（模塊）接口、可測(cè)試性四個(gè)方面闡述了軟件編程規(guī)范，規(guī)范分成規(guī)則和建議兩種，其中規(guī)則部分為強(qiáng)制執(zhí)行項(xiàng)目，而建議部分則不作強(qiáng)制，可根據(jù)習(xí)慣取舍。

1 ．排版
規(guī)則 1
程序塊使用縮進(jìn)方式，函數(shù)和標(biāo)號(hào)使用空格縮進(jìn)，程序段混合使用 TAB 和空格縮進(jìn)。縮進(jìn)的目的是使程序結(jié)構(gòu)清晰，便于閱讀和理解。
<TAB> 默認(rèn)寬度應(yīng)為 8 個(gè)空格，由于 Word 中 <TAB> 為 4 個(gè)空格，為示范清晰，此處用 2 個(gè) <TAB> 代替 ( 下同 ) 。
例如：
????????MOV????????R1,?#00H
????????MOV????????R2,?#00H
????????MOV????????PMR,?#PMRNORMAL
????????MOV????????DPS,?#FLAGDPTR
????????MOV????????DPTR,?#ADDREEPROM
read1kloop:
??read1kpage:
????????INC????????R1
????????MOVX????A,?@DPTR
????????MOV????????SBUF,?A
?????????JNB????TI,? ＄
?????????CLR????TI?
????????INC????????DPTR
????????CJNE????R1,?#20H,?read1kpage
????????INC????????R2
????????MOV????????R1,?#00H
?????????CPL????WDI
????????CJNE????R2,?#20H,?read1kloop????????;END?OF?EEPROM

規(guī)則 2?
在指令的操作數(shù)之間的，使用空格進(jìn)行間隔，采用這種松散方式編寫(xiě)代碼的目的是使代碼更加清晰。
例如：
????????CJNE????R2,?#20H,?read1kloop????????;END?OF?EEPROM

規(guī)則 3?
一行最多寫(xiě)一條語(yǔ)句。

規(guī)則 4?
變量定義時(shí)，保持對(duì)齊。便于閱讀和檢查內(nèi)存的使用情況。
例如：
RegLEDLOSS????????EQU????????30H????????;?VARIABLE????????;?TESTLED==RegLEDLOSS.0
RegLEDRA????????EQU????????31H????????;?VARIABLE
RUNLED_Flag????????EQU????????32H????????;?VARIABLE?????????;?256ms 改變一次 RUNLED 狀態(tài)
RUNLED_Def????????EQU????????10H????????;?STATIC????????;?16*32ms=500ms 改變一次 LED 狀態(tài)


2 ．注釋
注釋的原則是有助于對(duì)程序的閱讀理解，注釋不宜太多也不能太少，太少不利于代碼理解，太多則會(huì)對(duì)閱讀產(chǎn)生干擾，因此只在必要的地方才加注釋?zhuān)易⑨屢獪?zhǔn)確、易懂、盡可能簡(jiǎn)潔。注釋量一般控制在 30% 到 50% 之間。

規(guī)則 1
程序在必要的地方必須有注釋?zhuān)⑨屢獪?zhǔn)確、易懂、簡(jiǎn)潔。
例如如下注釋意義不大：
????????MOV????????DXCE1COUNTER,?#00H????????;? 將 DXCE1COUNTER 賦值為 0
而如下的注釋則給出了額外有用的信息：
????????JNZ????????PcComm_Err????????????????;? 假如校驗(yàn)出錯(cuò)

規(guī)則 2?
注釋?xiě)?yīng)與其描述的代碼相近，對(duì)代碼的注釋?xiě)?yīng)放在其上方或右方（對(duì)單條語(yǔ)句的注釋?zhuān)┫噜徫恢茫豢煞旁谙旅妫绶庞谏戏絼t需與其上面的代碼用空行隔開(kāi)。

規(guī)則 3
頭文件、源文件的頭部，應(yīng)進(jìn)行注釋。注釋必須列出：文件名、作者、目的、功能、修改日志等。

規(guī)則 4
函數(shù)頭部應(yīng)進(jìn)行注釋?zhuān)谐觯汉瘮?shù)的目的、功能、輸入?yún)?shù)、輸出參數(shù)、涉及到的通用變量和寄存器、調(diào)用的其他函數(shù)和模塊、修改日志等。對(duì)一些復(fù)雜的函數(shù)，在注釋中最好提供典型用法。

規(guī)則 5
對(duì)重要代碼段的功能、意圖進(jìn)行注釋?zhuān)峁┯杏玫摹㈩~外的信息。并在該代碼段的結(jié)束處加一行注釋表示該段代碼結(jié)束。

規(guī)則 6
對(duì)于所有的常量，變量，數(shù)據(jù)結(jié)構(gòu)聲明 ( 包括數(shù)組、結(jié)構(gòu)、類(lèi)、枚舉等 ) ，如果其命名不是充分自注釋的，在聲明時(shí)都必須加以注釋?zhuān)f(shuō)明其含義。

規(guī)則 ?7
維護(hù)代碼時(shí)，要更新相應(yīng)的注釋?zhuān)瑒h除不再有用的注釋。保持代碼、注釋的一致性，避免產(chǎn)生誤解。


3 ．命名
規(guī)則 ?1
標(biāo)識(shí)符縮寫(xiě)
形成縮寫(xiě)的幾種技術(shù)：
1)???? 去掉所有的不在詞頭的元音字母。如 screen 寫(xiě)成 scrn,?primtive 寫(xiě)成 prmv 。
2)???? 使用每個(gè)單詞的頭一個(gè)或幾個(gè)字母。如 Channel?Activation 寫(xiě)成 ChanActiv ， Release?Indication 寫(xiě)成 RelInd 。
3)???? 使用變量名中每個(gè)有典型意義的單詞。如 Count?of?Failure 寫(xiě)成 FailCnt 。
4)???? 去掉無(wú)用的單詞后綴 ?ing,?ed 等。如 Paging?Request 寫(xiě)成 PagReq 。
5)???? 使用標(biāo)準(zhǔn)的或慣用的縮寫(xiě)形式（包括協(xié)議文件中出現(xiàn)的縮寫(xiě)形式）。如 BSIC(Base?Station?Identification?Code) 、 MAP(Mobile?Application?Part) 。
關(guān)于縮寫(xiě)的準(zhǔn)則：
1)???? 縮寫(xiě)應(yīng)該保持一致性。如 Channel 不要有時(shí)縮寫(xiě)成 Chan ，有時(shí)縮寫(xiě)成 Ch 。 Length 有時(shí)縮寫(xiě)成 Len ，有時(shí)縮寫(xiě)成 len 。
2)???? 在源代碼頭部加入注解來(lái)說(shuō)明協(xié)議相關(guān)的、非通用縮寫(xiě)。
3)???? 標(biāo)識(shí)符的長(zhǎng)度不超過(guò) 12 個(gè)字符。

規(guī)則 2
變量命名約定： < 前綴 >?+? 主體 ????????;? 注釋
變量命名要考慮簡(jiǎn)單、直觀、不易混淆。
前綴是可選項(xiàng)，表示變量類(lèi)型，由于匯編中變量多是單字節(jié)變量，所以單字節(jié)變量可以不加前綴，對(duì)于 bit 和雙字節(jié)型變量，使用小寫(xiě)的 b 和 d 作為前綴表示。
主體是必選項(xiàng)，可多個(gè)單詞 ( 或縮寫(xiě) ) 合在一起，每個(gè)單詞首字母大寫(xiě)，其余部分小寫(xiě)。

規(guī)則 3
常量的命名
常量的命名規(guī)則：?jiǎn)卧~的字母全部大寫(xiě)，各單詞之間用下劃線隔開(kāi)。

規(guī)則 4
函數(shù)的命名
單詞首字母為大寫(xiě)，其余均為小寫(xiě)。函數(shù)名應(yīng)以一個(gè)動(dòng)詞開(kāi)頭，即函數(shù)名應(yīng)類(lèi)似一個(gè)動(dòng)詞斷語(yǔ)或祈使句。
例如： Test_Protect ， ?Check_EEPROM ， ?Init_Para


4 ．可維護(hù)性
規(guī)則 1
函數(shù)和過(guò)程中關(guān)系較為緊密的代碼盡可能相鄰。

規(guī)則 2
每個(gè)函數(shù)的源程序行數(shù)原則上應(yīng)該少于 200 行。
對(duì)于消息分流處理函數(shù)，完成的功能統(tǒng)一，但由于消息的種類(lèi)多，可能超過(guò) 200 行的限制，不屬于違反規(guī)定。

規(guī)則 3
語(yǔ)句嵌套層次不得超過(guò) 5 層。
嵌套層次太多，增加了代碼的復(fù)雜度及測(cè)試的難度，容易出錯(cuò)，增加代碼維護(hù)的難度。

規(guī)則 4
避免相同的代碼段在多個(gè)地方出現(xiàn)。
當(dāng)某段代碼需在不同的地方重復(fù)使用時(shí)，應(yīng)根據(jù)代碼段的規(guī)模大小使用函數(shù)調(diào)用或宏調(diào)用的方式代替。這樣，對(duì)該代碼段的修改就可在一處完成，增強(qiáng)代碼的可維護(hù)性。

規(guī)則 5
每個(gè)函數(shù)完成單一的功能，不設(shè)計(jì)多用途面面俱到的函數(shù)。
多功能集于一身的函數(shù)，很可能使函數(shù)的理解、測(cè)試、維護(hù)等變得困難。使函數(shù)功能明確化，增加程序可讀性，亦可方便維護(hù)、測(cè)試。

規(guī)則 6
在函數(shù)的項(xiàng)目維護(hù)文檔中，應(yīng)該指出軟件適用的硬件平臺(tái)及版本。


建議 1
使用專(zhuān)門(mén)的初始化函數(shù)對(duì)所有的公共變量進(jìn)行初始化。


5 ．程序正確性、效率
規(guī)則 1
嚴(yán)禁使用未經(jīng)初始化的變量。
引用未經(jīng)初始化的變量可能會(huì)產(chǎn)生不可預(yù)知的后果，特別是引用未經(jīng)初始化的指針經(jīng)常會(huì)導(dǎo)致系統(tǒng)崩潰，需特別注意。

規(guī)則 2
防止內(nèi)存操作越界。
說(shuō)明：內(nèi)存操作越界是軟件系統(tǒng)主要錯(cuò)誤之一，后果往往非常嚴(yán)重。

規(guī)則 3
注意變量的有效取值范圍，防止表達(dá)式出現(xiàn)上溢或下溢。

規(guī)則 4
防止易混淆的指令和操作數(shù)拼寫(xiě)錯(cuò)誤。

規(guī)則 5
避免函數(shù)中不必要語(yǔ)句，防止程序中的垃圾代碼，預(yù)留代碼應(yīng)以注釋的方式出現(xiàn)。
程序中的垃圾代碼不僅占用額外的空間，而且還常常影響程序的功能與性能，很可能給程序的測(cè)試、維護(hù)等造成不必要的麻煩。

規(guī)則 6
通過(guò)對(duì)系統(tǒng)數(shù)據(jù)結(jié)構(gòu)的劃分與組織的改進(jìn)，以及對(duì)程序算法的優(yōu)化來(lái)提高空間效率。
這種方式是解決軟件空間效率的根本辦法。

規(guī)則 7
循環(huán)體內(nèi)工作量最小化。
應(yīng)仔細(xì)考慮循環(huán)體內(nèi)的語(yǔ)句是否可以放在循環(huán)體之外，使循環(huán)體內(nèi)工作量最小，從而提高程序的時(shí)間效率。

規(guī)則 8
在多重循環(huán)中，應(yīng)將最忙的循環(huán)放在最內(nèi)層。

規(guī)則 9
避免循環(huán)體內(nèi)含判斷語(yǔ)句，將與循環(huán)變量無(wú)關(guān)的判斷語(yǔ)句移到循環(huán)體外。
目的是減少判斷次數(shù)。循環(huán)體中的判斷語(yǔ)句是否可以移到循環(huán)體外，要視程序的具體情況而言，一般情況，與循環(huán)變量無(wú)關(guān)的判斷語(yǔ)句可以移到循環(huán)體外，而有關(guān)的則不可以。

規(guī)則 10
中斷和恢復(fù)
中斷程序應(yīng)該盡量短，應(yīng)該在中斷中進(jìn)行標(biāo)記，在主程序中處理。但實(shí)時(shí)性很高的程序段例外。
中斷時(shí)應(yīng)該保存所有涉及到的通用變量和寄存器，如 A,?PSW,?DPTR 等。

規(guī)則 11?
堆棧設(shè)置
堆棧對(duì)于程序非常重要，對(duì)于堆棧的設(shè)置要合理。堆棧太小，在嵌套調(diào)用和很容易溢出，造成系統(tǒng)故障；堆棧太大，浪費(fèi) RAM 資源。
為了節(jié)約堆棧資源，中斷時(shí)要求不要保存太多資源，中斷嵌套和程序嵌套層數(shù)不要太多，盡量不要超過(guò) 5 層。這就要求合理的劃分功能模塊。

規(guī)則 12
看門(mén)狗
看門(mén)狗電路用于在單片機(jī)死機(jī)時(shí)自動(dòng)復(fù)位。單片機(jī)需要定時(shí)向看門(mén)狗發(fā)送脈沖，俗稱(chēng)”喂狗”。喂狗不可太勤，這樣看門(mén)狗沒(méi)有起到作用；也不可太慢，這樣容易造成單片機(jī)復(fù)位。正確的喂狗應(yīng)該在主循環(huán)中進(jìn)行，最好是建立一個(gè)獨(dú)立的系統(tǒng)監(jiān)控進(jìn)程。不可以在定時(shí)中斷中喂狗，應(yīng)為單片機(jī)有時(shí)可能會(huì)在主循環(huán)中死掉。


6 ．接口
規(guī)則 1
去掉沒(méi)有必要的公共變量，編程時(shí)應(yīng)盡量少用公共變量。
公共變量是增大模塊間耦合的原因之一，故應(yīng)減少?zèng)]必要的公共變量以降低模塊間的耦合度。應(yīng)該構(gòu)造僅有一個(gè)模塊或函數(shù)可以修改、創(chuàng)建，而其余有關(guān)模塊或函數(shù)只訪問(wèn)的公共變量，防止多個(gè)不同模塊或函數(shù)都可以修改、創(chuàng)建同一公共變量的現(xiàn)象。

規(guī)則 2
當(dāng)向公共變量傳遞數(shù)據(jù)時(shí)，要防止越界現(xiàn)象發(fā)生。
對(duì)公共變量賦值時(shí)，若有必要應(yīng)進(jìn)行合法性檢查，以提高代碼的可靠性、穩(wěn)定性。

規(guī)則 3
盡量不設(shè)計(jì)多參數(shù)函數(shù)，將不使用的參數(shù)從接口中去掉，降低接口復(fù)雜度，減少函數(shù)間接口的復(fù)雜度。

規(guī)則 4
對(duì)所調(diào)用函數(shù)的返回碼要仔細(xì)、全面地處理。
防止把錯(cuò)誤傳遞到后面的處理流程。如有意不檢查其返回碼，應(yīng)明確指明。

規(guī)則 5
檢查接口函數(shù)所有輸入?yún)?shù)的有效性。

規(guī)則 6
檢查函數(shù)的所有非參數(shù)輸入，如外部數(shù)據(jù)、公共變量等。


7 ．代碼可測(cè)性
規(guī)則 1
模塊編寫(xiě)應(yīng)該有完善的測(cè)試方面的考慮。

規(guī)則 2
源代碼中應(yīng)該設(shè)計(jì)了代碼測(cè)試的內(nèi)容。
在編寫(xiě)代碼之前，應(yīng)預(yù)先設(shè)計(jì)好程序調(diào)試與測(cè)試的方法和手段，并設(shè)計(jì)好各種調(diào)測(cè)開(kāi)關(guān)及相應(yīng)測(cè)試代碼。
程序的調(diào)試與測(cè)試是軟件生存周期中很重要的一個(gè)階段，如何對(duì)軟件進(jìn)行較全面、高率的測(cè)試并盡可能地找出軟件中的錯(cuò)誤就成為很關(guān)鍵的問(wèn)題。因此在編寫(xiě)源代碼之前，除了要有一套比較完善的測(cè)試計(jì)劃外，還應(yīng)設(shè)計(jì)出一系列代碼測(cè)試手段，為單元測(cè)試、集成測(cè)試及系統(tǒng)聯(lián)調(diào)提供方便。

規(guī)則 3
在同一項(xiàng)目組或產(chǎn)品組內(nèi)，要有一套統(tǒng)一的為集成測(cè)試與系統(tǒng)聯(lián)調(diào)準(zhǔn)備的調(diào)測(cè)開(kāi)關(guān)及相應(yīng)函數(shù)，并且要有詳細(xì)的說(shuō)明。本規(guī)則是針對(duì)項(xiàng)目組或產(chǎn)品組的。

規(guī)則 4
在同一項(xiàng)目組或產(chǎn)品組內(nèi)，調(diào)測(cè)打印出的信息串的格式要有統(tǒng)一的形式。信息串中至少要有所在模塊名（或源文件名）及行號(hào)。
統(tǒng)一的調(diào)測(cè)信息格式便于集成測(cè)試。

規(guī)則 5
正式軟件產(chǎn)品中應(yīng)把調(diào)測(cè)代碼去掉（即把有關(guān)的調(diào)測(cè)開(kāi)關(guān)關(guān)掉）。

規(guī)則 6
用調(diào)測(cè)開(kāi)關(guān)來(lái)切換軟件的 DEBUG 版和正式版，而不要同時(shí)存在正式版本和 DEBUG 版本的不同源文件，以減少維護(hù)的難度。

規(guī)則 7
在軟件系統(tǒng)中設(shè)置與取消有關(guān)測(cè)試手段，不能對(duì)軟件實(shí)現(xiàn)的功能等產(chǎn)生影響。
即有測(cè)試代碼的軟件和關(guān)掉測(cè)試代碼的軟件，在功能行為上應(yīng)一致。

規(guī)則 8
發(fā)現(xiàn)錯(cuò)誤應(yīng)該立即修改，并且若有必要記錄下來(lái)。

規(guī)則 9
開(kāi)發(fā)人員應(yīng)堅(jiān)持對(duì)代碼進(jìn)行徹底的測(cè)試（單元測(cè)試），而不依靠他人或測(cè)試組來(lái)發(fā)現(xiàn)問(wèn)題。

規(guī)則 10
清理、整理或優(yōu)化后的代碼要經(jīng)過(guò)審查及測(cè)試。

規(guī)則 11
代碼版本升級(jí)要經(jīng)過(guò)嚴(yán)格測(cè)試。


8 ．代碼編譯
規(guī)則 1
打開(kāi)編譯器的所有告警開(kāi)關(guān)對(duì)程序進(jìn)行編譯。
防止隱藏可能是錯(cuò)誤的告警。

規(guī)則 2
某些語(yǔ)句經(jīng)編譯后產(chǎn)生告警，但如果你認(rèn)為它是正確的，那么應(yīng)通過(guò)某種手段去掉告警信息。


ps ：從網(wǎng)上收集了一些相關(guān)內(nèi)容，結(jié)合我自己的經(jīng)驗(yàn)，歡迎拍磚，謝絕辱罵；
ps2 ：有些可能不常用，因?yàn)榇蠹覍?xiě)不到那么長(zhǎng)的代碼，就我自己寫(xiě)的最長(zhǎng)的匯編代碼也不超過(guò) 10K 行； ?

?