軟體設計更多地是一種工程,而不是一種個人藝術。如果不統一編程規範,最終寫出的程序,其可讀性將較差,這不僅給代碼的理解帶來障礙,增加維護階段的工作量,同時不規範的代碼隱含錯誤的可能性也比較大。 分析表明,編碼階段產生的錯誤當中,語法錯誤大概佔20%左右,而由於未嚴格檢查軟體邏輯導致的錯誤、函數(模塊)之間介面錯誤及由於代碼可理解度低導致優化維護階段對代碼的錯誤修改引起的錯誤則佔了一半以上。 可見,提高軟體質量必須降低編碼階段的錯誤率。如何有效降低編碼階段的錯誤呢?這需要制定詳細的軟體編程規範,並培訓每一位程序員,最終的結果可以把編碼階段的錯誤降至10%左右,同時也降低了程序的測試費用,效果相當顯著。 本文從代碼的可維護性(可讀性、可理解性、可修改性)、代碼邏輯與效率、函數(模塊)介面、可測試性四個方面闡述了軟體編程規範,規範分成規則和建議兩種,其中規則部分為強制執行項目,而建議報分則不作強制,可根據習慣取捨。 1.排版 規則1 程序塊使用縮進方式,函數和標號使用空格縮進,程序段混合使用TAB和空格縮進。縮進的目的是使程序結構清晰,便於閱讀和理解。 默認寬度應為8個空格,由於Word中為4個空格,為示範清晰,此處用2個代替(下同)。 例如: 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 規則2 在指令的操作數之間的,使用空格進行間隔,採用這種鬆散方式編寫代碼的目的是使代碼更加清晰。 例如: CJNE R2, #20H, read1kloop ;END OF EEPROM 規則3 一行最多寫一條語句。 規則4 變數定義時,保持對齊。便於閱讀和檢查內存的使用情況。 例如: RegLEDLOSS EQU 30H ; VARIABLE ; TESTLED==RegLEDLOSS.0 RegLEDRA EQU 31H ; VARIABLE RUNLED_Flag EQU 32H ; VARIABLE ; 256ms改變一次RUNLED狀態 RUNLED_Def EQU 10H ; STATIC ; 16*32ms=500ms改變一次LED狀態 2.註釋 註釋的原則是有助於對程序的閱讀理解,註釋不宜太多也不能太少,太少不利於代碼理解,太多則會對閱讀產生干擾,因此只在必要的地方才加註釋,而且註釋要準確、易懂、儘可能簡潔。註釋量一般控制在30%到50%之間。 規則1 程序在必要的地方必須有註釋,註釋要準確、易懂、簡潔。 例如如下註釋意義不大: MOV DXCE1COUNTER, #00H ; 將DXCE1COUNTER賦值為0 而如下的註釋則給出了額外有用的信息: JNZ PcComm_Err ; 假如校驗出錯 規則2 註釋應與其描述的代碼相近,對代碼的註釋應放在其上方或右方(對單條語句的註釋)相鄰位置,不可放在下面,如放於上方則需與其上面的代碼用空行隔開。 規則3 頭文件、源文件的頭部,應進行註釋。註釋必須列出:文件名、作者、目的、功能、修改日誌等。 規則4 函數頭部應進行註釋,列出:函數的目的、功能、輸入參數、輸出參數、涉及到的通用變數和寄存器、調用的其他函數和模塊、修改日誌等。對一些複雜的函數,在註釋中最好提供典型用法。 規則5 對重要代碼段的功能、意圖進行註釋,提供有用的、額外的信息。並在該代碼段的結束處加一行註釋表示該段代碼結束。 規則6 對於所有的常量,變數,數據結構聲明(包括數組、結構、類、枚舉等),如果其命名不是充分自註釋的,在聲明時都必須加以註釋,說明其含義。 規則 7 維護代碼時,要更新相應的註釋,刪除不再有用的註釋。保持代碼、註釋的一致性,避免產生誤解。 3.命名 規則 1 標識符縮寫 形成縮寫的幾種技術: 1) 去掉所有的不在詞頭的母音字母。如screen寫成scrn, primtive寫成prmv。 2) 使用每個單詞的頭一個或幾個字母。如Channel Activation寫成ChanActiv,Release Indication寫成RelInd。 3) 使用變數名中每個有典型意義的單詞。如Count of Failure寫成FailCnt。 4) 去掉無用的單詞後綴 ing, ed等。如Paging Request寫成PagReq。 5) 使用標準的或慣用的縮寫形式(包括協議文件中出現的縮寫形式)。如BSIC(Base Station Identification Code)、MAP(Mobile Application Part)。 關於縮寫的準則: 1) 縮寫應該保持一致性。如Channel不要有時縮寫成Chan,有時縮寫成Ch。Length有時縮寫成Len,有時縮寫成len。 2) 在源代碼頭部加入註解來說明協議相關的、非通用縮寫。 3) 標識符的長度不超過12個字元。 規則2 變數命名約定:<前綴> + 主體 ; 註釋 變數命名要考慮簡單、直觀、不易混淆。 前綴是可選項,表示變數類型,由於彙編中變數多是單位元組變數,所以單位元組變數可以不加前綴,對於bit和雙位元組型變數,使用小寫的b和d作為前綴表示。 主體是必選項,可多個單詞(或縮寫)合在一起,每個單詞首字母大寫,其餘部分小寫。 規則3 常量的命名 常量的命名規則:單詞的字母全部大寫,各單詞之間用下劃線隔開。 規則4 函數的命名 單詞首字母為大寫,其餘均為小寫。函數名應以一個動詞開頭,即函數名應類似一個動詞斷語或祈使句。 例如:Test_Protect, Check_EEPROM, Init_Para 4.可維護性 規則1 函數和過程中關係較為緊密的代碼儘可能相鄰。 規則2 每個函數的源程序行數原則上應該少於200行。 對於消息分流處理函數,完成的功能統一,但由於消息的種類多,可能超過200行的限制,不屬於違反規疾。 規則3 語句嵌套層次不得超過5層。 嵌套層次太多,增加了代碼的複雜度及測試的難度,容易出錯,增加代碼維護的難度。 規則4 避免相同的代碼段在多個地方出現。 |