簡(jiǎn)介中興通訊軟件編程規(guī)范C/C是深圳市中興通訊股份有限公司于2003年發(fā)布并實(shí)施的企業(yè)設(shè)計(jì)技術(shù)標(biāo)準(zhǔn)主要面向使用C/C語(yǔ)言進(jìn)行產(chǎn)品軟件開(kāi)發(fā)的工程師與技術(shù)管理者用于統(tǒng)一編碼風(fēng)格解決代碼可讀性差、命名隨意、函數(shù)耦合度高、錯(cuò)誤處理不統(tǒng)一等團(tuán)隊(duì)開(kāi)發(fā)常見(jiàn)問(wèn)題。規(guī)范分為規(guī)則性與建議性兩類規(guī)則性條款要求嚴(yán)格執(zhí)行。內(nèi)容覆蓋基本原則、代碼布局、注釋寫法、命名規(guī)則、變量常量與類型、表達(dá)式與語(yǔ)句、函數(shù)與過(guò)程、可靠性、可測(cè)試性、斷言與錯(cuò)誤處理等章節(jié)不僅給出要求還配有大量正例、反例和說(shuō)明幫助理解“應(yīng)該怎樣寫”與“為什么不這樣寫”附錄另附編程模板和規(guī)范檢查表便于項(xiàng)目組直接落地執(zhí)行也可作為代碼走查的評(píng)分依據(jù)。壓縮包共1個(gè)doc文檔大小486KB以單文檔形式完整收錄了這份企業(yè)標(biāo)準(zhǔn)。資源已有301人瀏覽學(xué)習(xí)適合需要建立C/C編碼規(guī)范、開(kāi)展代碼質(zhì)量培訓(xùn)或進(jìn)行代碼評(píng)審的軟件開(kāi)發(fā)團(tuán)隊(duì)參考。1. 為什么一份 2003 年的 C/C 編碼規(guī)范值得今天再拆一遍“能編譯通過(guò)”很多時(shí)候是假象。C/C 的不少高危寫法——懸空的 else、跨 case 的變量聲明、裸指針加無(wú)長(zhǎng)度參數(shù)——編譯器不報(bào)錯(cuò)只在運(yùn)行時(shí)以崩潰或數(shù)據(jù)錯(cuò)亂的方式兌現(xiàn)后果。某通信設(shè)備制造企業(yè)早早在 2003 年發(fā)布并實(shí)施了內(nèi)部標(biāo)準(zhǔn)《軟件編程規(guī)范 — C/C》把布局、注釋、命名、可靠性、可測(cè)試性、斷言與錯(cuò)誤處理拆成了幾十條可執(zhí)行的條款并要求此后所有新寫代碼一律遵循。這份規(guī)范今天拆開(kāi)看并不陳舊因?yàn)樗i定的全是 C/C 編譯器不會(huì)替你查、但事故卻總愛(ài)去的地方。理解它為什么這樣設(shè)計(jì)等于看懂一個(gè)成熟的工業(yè)團(tuán)隊(duì)如何在編譯器之外建立第二道防線。2. 規(guī)則體系與布局排版如何變成工程能力的底層機(jī)制2.1 原則、規(guī)則與建議三級(jí)約束的“執(zhí)行彈性”機(jī)制規(guī)范開(kāi)篇就定義了三種條款等級(jí)原則、規(guī)則、建議。原則是“編程時(shí)應(yīng)該堅(jiān)持的指導(dǎo)思想”比如原則 1-1“首先是為人編寫程序其次才是計(jì)算機(jī)”規(guī)則是“編程時(shí)必須遵守的約定”建議是“編程時(shí)必須加以考慮的約定”。這個(gè)三級(jí)體系不是文檔排版的花架子它解決的是一個(gè)實(shí)際治理問(wèn)題一份要覆蓋多個(gè)產(chǎn)品線、多種嵌入式平臺(tái)和不同項(xiàng)目節(jié)奏的內(nèi)部標(biāo)準(zhǔn)若所有條款都寫成“必須”那在性能敏感或資源受限的模塊里就注定會(huì)出現(xiàn)大量豁免?；砻庖坏┬纬蓱T例標(biāo)準(zhǔn)整體就失去約束力。因此文檔用“規(guī)則”鎖死那些破壞后有明確負(fù)面后果的做法例如不加{}的單行 if、不用頭文件守衛(wèi)用“建議”保留那些破壞后只是可讀性下降的寫法例如變量擺放順序、注釋密度。把這一層想清楚能解釋后續(xù)很多條文的語(yǔ)氣差異。比如“避免或少用全局變量”是原則級(jí)表述因?yàn)樗皇恰敖^對(duì)禁止”而是權(quán)衡后的方向但“禁止使用 TAB 鍵必須使用空格縮進(jìn)”寫成了規(guī)則因?yàn)?TAB 在不同編輯器里寬度不一致會(huì)直接破壞所有成員看到同一份代碼的視覺(jué)基礎(chǔ)。機(jī)制上這套分級(jí)相當(dāng)于給每個(gè)條款配了不同的執(zhí)行強(qiáng)度讓規(guī)范既能守住底線又不至于在特殊場(chǎng)景下自廢武功。原則的排序同樣有深意?！熬幊虝r(shí)首先達(dá)到正確性其次考慮效率”被列在可靠性章節(jié)之前等于提前聲明了后續(xù)所有防御性條款的優(yōu)先級(jí)。C/C 項(xiàng)目的線上事故大多發(fā)生在邊界路徑而不是主路徑的熱點(diǎn)代碼上所以先保證邏輯正確、資源不泄漏、輸入有校驗(yàn)再去談微優(yōu)化。這一點(diǎn)也解釋了為什么規(guī)范敢要求檢查外部輸入、關(guān)注邊界條件——這些開(kāi)銷在正確性面前都被視為必要成本。2.2 頭文件與實(shí)現(xiàn)文件的固定“目錄”讓依賴關(guān)系一眼可見(jiàn)規(guī)范分別給頭文件和實(shí)現(xiàn)文件規(guī)定了固定的書(shū)寫次序。頭文件依次是文件頭注釋、#ifndef防重復(fù)包含宏、標(biāo)準(zhǔn)庫(kù)#include、非標(biāo)準(zhǔn)庫(kù)#include、常量定義、全局宏、全局?jǐn)?shù)據(jù)類型、類定義與模板、函數(shù)原型、#endif。實(shí)現(xiàn)文件則從文件頭注釋開(kāi)始依次是#include、常量、文件內(nèi)宏、文件內(nèi)數(shù)據(jù)類型、靜態(tài)全局變量、局部函數(shù)原型、類實(shí)現(xiàn)、全局函數(shù)與局部函數(shù)。注意實(shí)現(xiàn)文件里反復(fù)出現(xiàn)“文件內(nèi)”三個(gè)字它要求不對(duì)外暴露的符號(hào)盡量用static或匿名命名空間收束在編譯單元內(nèi)。這個(gè)固定目錄的收益在工程上是雙重的。第一重是閱讀秩序任何接手代碼的人翻一個(gè)文件十分鐘就能知道哪里找類型、哪里找宏、哪里找函數(shù)實(shí)現(xiàn)不用靠經(jīng)驗(yàn)猜。第二重是依賴顯性化頭文件的#include列表就是對(duì)外接口的依賴清單實(shí)現(xiàn)文件的#include列表則是內(nèi)部實(shí)現(xiàn)的依賴清單。兩者被格式強(qiáng)制分開(kāi)后審代碼的人一眼能看出接口層是否悄悄混入了實(shí)現(xiàn)細(xì)節(jié)——例如一個(gè)頭文件里包含了只在 .c 文件里才需要的內(nèi)部頭文件這就是依賴污染的信號(hào)。防重復(fù)包含的機(jī)制值得單獨(dú)展開(kāi)。規(guī)范給出的正例是#ifndef MODULE_H #define MODULE_H /* 文件體 */ #endif#ifndef到#endif構(gòu)成一個(gè)條件編譯塊。第一次包含該頭文件時(shí)MODULE_H未定義預(yù)處理器進(jìn)入文件體并順手定義MODULE_H第二次再包含時(shí)MODULE_H已存在預(yù)處理器跳過(guò)整個(gè)文件體。這就是宏名充當(dāng)“已包含標(biāo)記”的原理。正因?yàn)闄C(jī)制依賴宏名的全局唯一性規(guī)范要求守衛(wèi)宏用文件名全大寫來(lái)命名避免兩個(gè)頭文件因守衛(wèi)同名而互相誤傷——第二個(gè)文件會(huì)被當(dāng)成“已經(jīng)包含”而靜默跳過(guò)于是它的聲明整體缺失隨后就是報(bào)錯(cuò)或者更難查的隱式聲明。2.3 縮進(jìn)、括號(hào)與空格排版規(guī)則里的語(yǔ)法級(jí)理由布局章節(jié)的硬性規(guī)則細(xì)看幾乎每條都有語(yǔ)言或工具的根因。“禁止使用 TAB縮進(jìn)為 4 個(gè)空格”根因是 TAB 的渲染寬度取決于編輯器設(shè)置同一文件在不同環(huán)境下會(huì)顯示成不同錯(cuò)位而空格是唯一在所有編輯器里寬度一致的字符?？s進(jìn)幅度定為 4 格也經(jīng)過(guò)權(quán)衡2 格在深層嵌套時(shí)會(huì)糊成一片8 格在函數(shù)套函數(shù)時(shí)迅速把行寬擠爆4 格是閱讀密度和行寬消耗的均衡點(diǎn)?！癷f、else、for、while 等語(yǔ)句自占一行執(zhí)行語(yǔ)句不得緊跟其后不論執(zhí)行語(yǔ)句有多少都要加{}”這條同樣有明確語(yǔ)法背景。C 系語(yǔ)言的 else 遵循就近匹配不加大括號(hào)時(shí)一旦有人日后在 if 和 else 之間插入一行語(yǔ)句else 的歸屬就可能悄悄改變。規(guī)范給出的反例是if (varible1 varible2) varible1 varible2;正例里則把執(zhí)行語(yǔ)句放進(jìn)花括號(hào)if (varible1 varible2) { varible1 varible2; }加花括號(hào)的直接效果是把分支邊界從文字層面固定下來(lái)后期增刪語(yǔ)句都不會(huì)改變控制流結(jié)構(gòu)。規(guī)則還規(guī)定{和}獨(dú)占一行并與引用它們的語(yǔ)句左對(duì)齊這讓嵌套層級(jí)在視覺(jué)上變成清晰的垂直折線匹配括號(hào)、做代碼折疊、排查漏寫}都容易得多。指針聲明*的位置規(guī)范給出了明確主張float *pfBuffer; /* 規(guī)范寫法 */ float* pfBuffer; /* 反例 */這條看似是風(fēng)格之爭(zhēng)實(shí)際是語(yǔ)法結(jié)構(gòu)之爭(zhēng)。C/C 聲明語(yǔ)法里*屬于聲明符修飾的是變量名而非類型名。把*緊貼類型寫成float* pA, pB;視覺(jué)上會(huì)誘導(dǎo)人認(rèn)為pB也是指針但語(yǔ)法上pB只是 float。規(guī)范要求的寫法則讓每個(gè)變量前的*單獨(dú)顯形多變量聲明時(shí)誰(shuí)是指針一目了然。運(yùn)算符空格規(guī)則也是為同一目的服務(wù)一元操作符如!、~、、--前后不加空格多元運(yùn)算符與操作數(shù)之間至少留一個(gè)空格關(guān)鍵字后要留空格而函數(shù)名后不要。這套規(guī)則的本質(zhì)是制造視覺(jué)語(yǔ)法分類器——看到for (i...)知道是控制結(jié)構(gòu)看到Foo(...)知道是函數(shù)調(diào)用看到a b知道是算術(shù)表達(dá)式?！?向后緊跟、)、,,; 向前緊跟”這些細(xì)規(guī)則把復(fù)雜表達(dá)式里的括號(hào)和分隔符變成緊貼結(jié)構(gòu)減少閱讀時(shí)把括號(hào)看作多層嵌套的心理負(fù)擔(dān)。2.4 注釋的分層在意圖層寫作而不是翻譯代碼規(guī)范對(duì)注釋的定位非常明確注釋的價(jià)值在于提供代碼表面之外的額外信息例如功能意圖、設(shè)計(jì)約束、調(diào)用約定而不是把i解釋成“i 加一”。這背后是對(duì)維護(hù)成本的判斷——代碼是給編譯器讀的注釋是給下一個(gè)維護(hù)者讀的。逐行翻譯式注釋沒(méi)有任何信息增量真正有意義的是“為什么這樣寫”“有什么前置條件”“在哪種場(chǎng)景下會(huì)失效”。規(guī)范把注釋格式也做了統(tǒng)一多行注釋用/* ... */單行注釋用// ...注釋符與內(nèi)容之間留一個(gè)空格文件頭要有標(biāo)識(shí)功能、作者意圖的注釋塊。這些細(xì)節(jié)放在一起形成一種可預(yù)期的“注釋節(jié)奏”閱讀代碼時(shí)注釋不會(huì)干擾語(yǔ)句結(jié)構(gòu)但會(huì)在關(guān)鍵節(jié)點(diǎn)給出背景。結(jié)合布局規(guī)則看注釋塊同時(shí)承擔(dān)“分隔節(jié)”的作用——用規(guī)范的注釋塊把常量定義、類型定義、函數(shù)原型各自圈出來(lái)等于在代碼文件里建立了章節(jié)導(dǎo)航。3. 命名、注釋與類型編譯器看不見(jiàn)的語(yǔ)義契約3.1 匈牙利命名法把類型信息住進(jìn)標(biāo)識(shí)符規(guī)范示例里大量出現(xiàn)iLength、pfBuffer、aiNumbers、strCaption、wHead、ucCallNo、m_iCount、tPDBRes這類名字這是典型的匈牙利命名法。前綴承擔(dān)類型語(yǔ)義i表示整型f表示浮點(diǎn)w表示 16 位字長(zhǎng)uc表示 unsigned charstr表示字符串p表示指針ai表示整型數(shù)組m_表示類成員t表示結(jié)構(gòu)體類型。在 2003 年的開(kāi)發(fā)環(huán)境里這套前綴體系幾乎是“移動(dòng)端類型提示”。當(dāng)時(shí)沒(méi)有今天這么成熟的代碼跳轉(zhuǎn)和懸浮類型信息看一個(gè)函數(shù)體時(shí)變量類型主要靠聲明位置和命名推斷。pfBuffer五個(gè)字符直接告訴你“這是 float 指針、指向一塊緩沖區(qū)”不用回頭翻聲明wAddress直接提示 16 位寬度的寄存器值。這類信息對(duì)長(zhǎng)代碼維護(hù)極其有價(jià)值尤其是通信設(shè)備上大量與硬件寄存器、協(xié)議字段打交道的代碼類型寬度本身就是業(yè)務(wù)語(yǔ)義的一部分。更實(shí)際的機(jī)制收益是可檢索性。成員變量統(tǒng)一m_前綴審查者可以用正則把整個(gè)文件的成員訪問(wèn)全部篩出來(lái)全局變量如果統(tǒng)一前綴代碼評(píng)審時(shí)可以快速排查跨模塊耦合。規(guī)范另外要求類名以大寫字母開(kāi)頭如CCount、常量全大寫、函數(shù)名用動(dòng)詞性短語(yǔ)這些約定合并起來(lái)讓“按名字檢索”成為可靠的代碼導(dǎo)航手段。當(dāng)代 IDE 弱化了一部分前綴需求但指針、數(shù)組、句柄這些易錯(cuò)類型上保留前綴仍然是降低誤讀成本的有效做法。3.2 常量與類型的邊界宏、const、typedef 與全局變量的取舍變量、常量與類型章節(jié)的核心約束是控制“狀態(tài)的可見(jiàn)范圍”。全局變量被列為“避免或少用”因?yàn)槿譅顟B(tài)天然跨模塊可見(jiàn)任何函數(shù)都能讀寫任何時(shí)序都可能依賴它模塊邊界被隱式穿透。規(guī)范給出的緩解辦法也符合模塊化機(jī)制把全局變量收進(jìn)實(shí)現(xiàn)文件的文件作用域用static限定讓它在編譯單元內(nèi)部可見(jiàn)但對(duì)外不可見(jiàn)外部模塊要訪問(wèn)只能通過(guò)函數(shù)接口這樣依賴關(guān)系被顯式化。類型定義層面規(guī)范示例中的typedef unsigned char BOOLEAN;很有代表性。接口層用BOOLEAN而不是赤裸裸的unsigned char好處有兩層一是語(yǔ)義清晰看到BOOLEAN就知道這是布爾邏輯而不是字節(jié)運(yùn)算二是可替換性將來(lái)底層要改成int或其他表示時(shí)只改一處typedef。這類類型抽象在通信協(xié)議代碼里尤其重要——協(xié)議字段的字節(jié)序、位寬、有無(wú)符號(hào)集中定義后不容易在多處各自走樣。常量定義同樣有選擇問(wèn)題。規(guī)范更看重集中定義和全大寫命名但沒(méi)有把#define一棍子打死。在 C 語(yǔ)言里#define宏不參與類型檢查展開(kāi)階段直接做文本替換容易帶來(lái)類型隱患const修飾符則有類型語(yǔ)義能被編譯器檢查。規(guī)范的精神接近于“盡量用編譯器可檢查的手段表達(dá)常量”同時(shí)對(duì)宏的副作用保持警惕——例如宏參數(shù)不寫括號(hào)導(dǎo)致的優(yōu)先級(jí)問(wèn)題也是經(jīng)典翻車點(diǎn)。3.3 表達(dá)式與控制語(yǔ)句把歧義消滅在結(jié)構(gòu)層表達(dá)式與控制語(yǔ)句章節(jié)把許多“編譯器允許但語(yǔ)義危險(xiǎn)”的寫法做了顯式約束。if、for、while關(guān)鍵字后留空格再跟左括號(hào)函數(shù)名后緊跟左括號(hào)不留空格這條規(guī)則制造了控制關(guān)鍵字與函數(shù)調(diào)用在視覺(jué)上的區(qū)分。更細(xì)的規(guī)則是(向后緊跟、)和,向前緊跟、逗號(hào)后留空格——這樣寫for (i 0; i MAX_BSC_NUM; i) { DoSomething(iWidth, iHeight); }閱讀者掃一眼就能判斷for是循環(huán)、DoSomething是調(diào)用不會(huì)被括號(hào)的排版干擾。條件表達(dá)式的續(xù)行要求“在第一個(gè)條件處對(duì)齊”函數(shù)調(diào)用的續(xù)行要求“在第一個(gè)參數(shù)處對(duì)齊”賦值語(yǔ)句續(xù)行要求“在賦值號(hào)處對(duì)齊”這些都讓多行表達(dá)式保持單一視覺(jué)錨點(diǎn)不會(huì)因?yàn)閾Q行產(chǎn)生歧義。switch 語(yǔ)句的規(guī)則值得單獨(dú)強(qiáng)調(diào)。規(guī)范要求每個(gè) case 分支和 default 都用{}括起來(lái)例如switch (iCode) { case 1: { DoSomething(); break; } case 2: { DoOtherThing(); break; } default: { DoNothing(); break; } }深層原因是 C 的作用域規(guī)則case 標(biāo)簽本身不建立作用域塊。若在 case 分支里直接聲明變量而不加{}該變量會(huì)跨越整個(gè) switch 作用域可見(jiàn)其他分支跳轉(zhuǎn)過(guò)來(lái)時(shí)就會(huì)跨越初始化點(diǎn)觸發(fā)編譯錯(cuò)誤或未定義行為。加上{}后每個(gè)分支成為獨(dú)立作用域變量聲明被局限在本分支內(nèi)跳轉(zhuǎn)邏輯也被結(jié)構(gòu)化。這條規(guī)則本質(zhì)上是把“語(yǔ)言默認(rèn)的危險(xiǎn)行為”通過(guò)排版改成“結(jié)構(gòu)上安全的行為”。4. 可靠性、斷言與可測(cè)試性把故障在發(fā)布前逼出來(lái)4.1 可靠性條款輸入校驗(yàn)與資源回滾機(jī)制可靠性章節(jié)是這個(gè)規(guī)范里信息密度最高的地方它針對(duì) C/C 最常見(jiàn)的三類運(yùn)行時(shí)事故——非法輸入、越界訪問(wèn)、資源泄漏——分別立規(guī)。凡是外部輸入進(jìn)入函數(shù)邊界時(shí)就要做合法性檢查凡是接收緩沖區(qū)調(diào)用方要同時(shí)傳入長(zhǎng)度凡是申請(qǐng)了資源就必須有對(duì)應(yīng)的釋放路徑。這些條款在嵌入式通信設(shè)備上尤其關(guān)鍵因?yàn)樵O(shè)備長(zhǎng)期在線運(yùn)行一次內(nèi)存泄漏或一次越界寫都可能累積成不可恢復(fù)的系統(tǒng)故障。資源管理的規(guī)則最能體現(xiàn)“成對(duì)出現(xiàn)”的機(jī)制思想。規(guī)范要求資源的申請(qǐng)與釋放在清晰的模塊邊界內(nèi)成對(duì)分配失敗時(shí)已經(jīng)申請(qǐng)的資源要全部回滾。落到代碼上典型的實(shí)現(xiàn)是逐級(jí)回退int InitResource(void) { void *pBuf malloc(BUF_SIZE); if (pBuf NULL) { return -1; } int iFd open(DEV_NAME, O_RDWR); if (iFd 0) { free(pBuf); /* 一處失敗回滾上一步 */ return -1; } return 0; }這里的可靠性機(jī)制是“失敗路徑逆序清理”。每新增一個(gè)資源就新增一個(gè)失敗出口某個(gè)資源申請(qǐng)失敗時(shí)之前成功的資源沿相反順序逐個(gè)釋放。審查者核對(duì)這段代碼時(shí)只需要把申請(qǐng)順序倒過(guò)來(lái)對(duì)照釋放順序就能判斷是否存在泄漏路徑。相比把所有free集中在函數(shù)末尾的寫法逐級(jí)回退的優(yōu)點(diǎn)是職責(zé)就近資源生命周期一目了然不會(huì)因?yàn)橹虚g加了分支而漏掉某條路徑的清理動(dòng)作。4.2 斷言與錯(cuò)誤處理分清楚“必崩”和“可恢復(fù)”斷言章節(jié)和錯(cuò)誤處理章節(jié)被規(guī)范放在一起這本身就是一種機(jī)制設(shè)計(jì)二者是分工關(guān)系不是替代關(guān)系。斷言應(yīng)該用來(lái)捕獲“程序員的錯(cuò)誤”——內(nèi)部不變量被破壞、指針不該為空卻為空、狀態(tài)不該出現(xiàn)卻出現(xiàn)了錯(cuò)誤處理則用來(lái)應(yīng)對(duì)“外部世界的錯(cuò)誤”——用戶輸入非法、網(wǎng)絡(luò)報(bào)文截?cái)?、設(shè)備返回異常。把二者分開(kāi)等于給代碼定了一條契約邊界斷言崩在開(kāi)發(fā)期讓開(kāi)發(fā)者立刻知道邏輯錯(cuò)了錯(cuò)誤處理?yè)卧谶\(yùn)行期讓程序?qū)ν獠慨惓１３纸导?jí)能力。實(shí)現(xiàn)層的關(guān)鍵是斷言的可裁剪性。典型的斷言庫(kù)會(huì)用NDEBUG宏控制#ifndef NDEBUG #define assert(expr) ((expr) ? (void)0 : abort()) #else #define assert(expr) ((void)0) #endif發(fā)布構(gòu)建里定義NDEBUG后斷言調(diào)用變成空操作不產(chǎn)生任何運(yùn)行時(shí)開(kāi)銷。這個(gè)機(jī)制帶來(lái)一個(gè)必須遵守的推論斷言不能承擔(dān)任何“正常流程可能失敗”的檢查。比如輸入?yún)?shù)是否為空指針如果這是外部輸入就絕不能靠assert(pData ! NULL)攔截因?yàn)樗鼤?huì)在發(fā)布版里被剝掉非法指針繼續(xù)往下走故障以更隱蔽的方式爆掉。正確的姿勢(shì)是:assert(pData ! NULL); /* 契約內(nèi)部邏輯保證這里非空 */ if (pData NULL) { /* 防御外部輸入可能有誤 */ return ERROR_INVALID_PARAM; }斷言表達(dá)“這里不該出錯(cuò)”if表達(dá)“這里出錯(cuò)很正?！?。一旦把二者混用要么發(fā)布版失去保護(hù)要么正常業(yè)務(wù)錯(cuò)誤直接觸發(fā)進(jìn)程終止。規(guī)范里還有一個(gè)易被忽略的細(xì)節(jié)函數(shù)原型要求寫int Foo(void)而不是int Foo()。在舊式 C 語(yǔ)法里int Foo()表示“參數(shù)類型未定義”編譯器不做實(shí)參校驗(yàn)int Foo(void)才是“不接受任何參數(shù)”的明確聲明。寫清楚void等于消掉了一類未定義行為的歧義。4.3 可測(cè)試性讓故障可觀測(cè)的源碼結(jié)構(gòu)可測(cè)試性章節(jié)關(guān)心的是當(dāng)故障真的發(fā)生時(shí)代碼結(jié)構(gòu)能不能幫人快速定位。規(guī)范給出的路徑是函數(shù)單一職責(zé)、控制參數(shù)個(gè)數(shù)、避免函數(shù)內(nèi)部大量隱式依賴全局狀態(tài)。單一職責(zé)函數(shù)的收益在測(cè)試層面非常直接輸入可構(gòu)造、輸出可斷言、副作用可控制。如果一個(gè)函數(shù)同時(shí)負(fù)責(zé)解析報(bào)文、修改全局表、寫日志、觸發(fā)消息那任何輸入組合的驗(yàn)證都會(huì)牽動(dòng)多個(gè)模塊故障定位也無(wú)從下手。與可測(cè)試性配套的是信息封裝規(guī)則。規(guī)范要求實(shí)現(xiàn)文件把不對(duì)外暴露的函數(shù)、變量收進(jìn)文件內(nèi)只暴露必要接口這讓測(cè)試目標(biāo)明確被測(cè)試的是公開(kāi)接口內(nèi)部結(jié)構(gòu)可以在不破壞契約的前提下重構(gòu)。同時(shí)錯(cuò)誤路徑必須通過(guò)返回值或顯式錯(cuò)誤碼表達(dá)而不是靠全局標(biāo)志位。把這幾點(diǎn)合并起來(lái)看可測(cè)試性章節(jié)的底層邏輯是任何故障都應(yīng)該能被觀測(cè)任何觀測(cè)都應(yīng)能定位到函數(shù)。這與現(xiàn)代可觀測(cè)性思想同源只是 2003 年它把“可觀測(cè)”落實(shí)在源碼的組織紀(jì)律上而不是日志與監(jiān)控平臺(tái)。5. 避坑實(shí)錄執(zhí)行編碼規(guī)范時(shí)繞不開(kāi)的 5 個(gè)現(xiàn)場(chǎng)5.1 頭文件守衛(wèi)寫了還是出現(xiàn)重定義現(xiàn)象兩個(gè)模塊都寫了#ifndef MODULE_H單獨(dú)編譯各自正常聯(lián)合編譯時(shí)卻出現(xiàn)類型或宏重復(fù)定義。原因守衛(wèi)宏的作用域是整個(gè)編譯單元。兩個(gè)不同頭文件用了同一個(gè)宏名時(shí)第二個(gè)頭文件的#ifndef條件不成立整個(gè)文件體被預(yù)處理器跳過(guò)等于“聲明從未發(fā)生過(guò)”而其他源文件各自包含它們后外部符號(hào)定義又按某種順序暴露出來(lái)于是出現(xiàn)重定義或聲明缺失的交替報(bào)錯(cuò)。這個(gè)坑的根源是守衛(wèi)宏依賴全局唯一命名僅靠“守衛(wèi)存在”并不足以保證正確。解決守衛(wèi)宏必須與文件名唯一對(duì)應(yīng)并加上工程前綴例如#ifndef MODULE_H改成#ifndef ZX_MODULE_H之類的唯一形態(tài)同時(shí)把#endif放在文件最末不在守衛(wèi)內(nèi)混入多余的代碼。提交前用腳本掃描所有頭文件檢查守衛(wèi)名與文件名是否一一對(duì)應(yīng)可以把這個(gè)坑徹底封死。5.2 縮進(jìn)看著對(duì)齊換個(gè)編輯器全部錯(cuò)位現(xiàn)象代碼在自己編輯器里整整齊齊推到另一臺(tái)機(jī)器或 CI 差異視圖里花括號(hào)、注釋、續(xù)行全部錯(cuò)位甚至讓人誤判嵌套關(guān)系。原因代碼里有真實(shí)存在的 TAB 字符。TAB 的渲染寬度取決于編輯器默認(rèn)值有的按 4 格有的按 8 格有的按“對(duì)齊到下一個(gè)制表位”于是同一字符在不同環(huán)境顯示成不同寬度?？s進(jìn)一旦錯(cuò)位“視覺(jué)對(duì)齊”這個(gè)機(jī)制就失效了嵌套層級(jí)的判斷靠肉眼必然出錯(cuò)。解決嚴(yán)格按規(guī)范的“禁止 TAB、縮進(jìn) 4 空格”執(zhí)行。把編輯器設(shè)置成輸入 TAB 時(shí)自動(dòng)替換為空格同時(shí)在代碼倉(cāng)庫(kù)的提交鉤子里加一道檢查凡是文件里出現(xiàn)\t字符就直接攔截。這類格式化約束在多人協(xié)作里不是審美問(wèn)題是跨環(huán)境一致性的地基。5.3 指針聲明寫成float*一行聲明兩個(gè)變量時(shí)埋雷現(xiàn)象某處寫了float* pA, pB;后續(xù)維護(hù)者把pB當(dāng)指針使用傳入函數(shù)后發(fā)生非法訪問(wèn)崩潰現(xiàn)場(chǎng)還看不出類型問(wèn)題。原因語(yǔ)法層面*綁定的是聲明符變量名不綁定類型符。float* pA, pB中pA是指針pB是 float。把*緊貼類型會(huì)讓閱讀者的視覺(jué)類型判斷與語(yǔ)法的實(shí)際類型不一致。視覺(jué)判斷一旦與語(yǔ)法不符后續(xù)使用就容易踩線。解決按規(guī)范把*放在變量名前寫成float *pA, *pB;。它雖然寫起來(lái)長(zhǎng)一點(diǎn)但每個(gè)變量名身旁的*都在各自聲明里獨(dú)立歸屬誰(shuí)是指針清清楚楚。更進(jìn)一步多指針聲明盡量拆成多行讓每個(gè)聲明自帶完整上下文誤讀概率才會(huì)真正降下來(lái)。5.4 switch 的 case 里聲明變量編譯報(bào)“跨初始化跳轉(zhuǎn)”現(xiàn)象case 分支里直接寫int iValue 0;打開(kāi)高警告級(jí)別編譯后報(bào)錯(cuò)內(nèi)容涉及 “crosses initialization”但加{}后消失。原因case 標(biāo)簽本身不建立作用域塊。直接聲明變量時(shí)這個(gè)變量被提升到整個(gè) switch 上下文其他 case 分支的跳轉(zhuǎn)路徑會(huì)“跨過(guò)”這個(gè)變量的初始化語(yǔ)句而 C 規(guī)則禁止跳過(guò)帶非平凡初始化的變量聲明所以編譯器亮紅燈。這不是警告而是硬錯(cuò)誤但根因容易被人誤讀成“編譯器抽風(fēng)”。解決按規(guī)范給每個(gè) case 分支加{}把變量聲明關(guān)進(jìn)獨(dú)立作用域。這樣每個(gè)分支自成一體跳轉(zhuǎn)不再跨越初始化點(diǎn)。實(shí)踐里這還會(huì)順手解決另一個(gè)問(wèn)題case 分支之間不寫break導(dǎo)致的貫穿執(zhí)行在{}結(jié)構(gòu)下更容易被肉眼發(fā)現(xiàn)。5.5 斷言和錯(cuò)誤處理混用線上程序被 assert 打崩現(xiàn)象發(fā)布版本收到崩潰報(bào)告棧頂停在斷言行查代碼發(fā)現(xiàn)斷言是用來(lái)攔截“用戶輸入非法”的。原因發(fā)布構(gòu)建通常定義NDEBUG斷言調(diào)用會(huì)被整個(gè)編譯掉但有些團(tuán)隊(duì)的發(fā)布構(gòu)建沒(méi)有統(tǒng)一關(guān)斷言或者更常見(jiàn)的是工程師把斷言當(dāng)成了參數(shù)校驗(yàn)手段在 debug 構(gòu)建里一切正常發(fā)布構(gòu)建里斷言消失后非法輸入長(zhǎng)驅(qū)直入故障以更隱蔽的方式爆出來(lái)。解決斷言只負(fù)責(zé)內(nèi)部不變量外部輸入校驗(yàn)一律走錯(cuò)誤碼或顯式的條件分支。發(fā)布構(gòu)建統(tǒng)一編譯選項(xiàng)明確禁用斷言關(guān)鍵業(yè)務(wù)路徑上對(duì)失敗要記錄日志而不是靜默。要把“這是外部世界可能帶來(lái)的錯(cuò)誤”和“這是程序內(nèi)部不該發(fā)生的錯(cuò)誤”這兩類判斷寫進(jìn)代碼評(píng)審的標(biāo)準(zhǔn)里而不是依賴某一個(gè)人當(dāng)時(shí)的狀態(tài)。6. 取舍與演進(jìn)規(guī)范給你的是底線不是標(biāo)準(zhǔn)答案回看這份規(guī)范最值得琢磨的不是某一條規(guī)則的正誤而是它作為一個(gè)整體展現(xiàn)出的取舍邏輯。第一組取舍是“統(tǒng)一性”與“差異性”。它用規(guī)則/建議分級(jí)來(lái)平衡破壞后會(huì)產(chǎn)生系統(tǒng)性故障的寫進(jìn)規(guī)則破壞后只是不好看的放進(jìn)建議。今天復(fù)刻這套思路時(shí)更高效的路徑是反著來(lái)——先把所有“建議級(jí)”條目交給格式化工具和 CI 校驗(yàn)去執(zhí)行再把人工評(píng)審的注意力集中在“規(guī)則級(jí)”的可靠性、斷言邊界、命名語(yǔ)義上。2003 年沒(méi)有自動(dòng)格式化縮進(jìn)對(duì)齊只能靠人腦執(zhí)行今天的工具鏈已經(jīng)把這些變成零成本真正貴的是讓工程師把“工具查不出的約定”內(nèi)化成習(xí)慣。第二組取舍是“正確性優(yōu)先”與“效率靈活性”。原則 1-4 排好了序正確性先于效率。這不只是口號(hào)它支撐著后續(xù)所有防御性條款的成立。通信設(shè)備這類長(zhǎng)生命周期產(chǎn)品代碼交付后要在線運(yùn)行數(shù)年維護(hù)成本遠(yuǎn)高于開(kāi)發(fā)成本一次線上內(nèi)存越界或資源泄漏可能需要排查幾周。規(guī)范選擇在開(kāi)發(fā)階段付出少量檢查開(kāi)銷換取運(yùn)行階段的事故概率下降這本質(zhì)上是用前置約束換后期自由。要清醒地看到這份規(guī)范的年代局限。它沒(méi)有涉及異常安全、RAII 資源管理這些現(xiàn)代 C 特性因?yàn)?2003 年的主流編譯器對(duì)模板和異常支持的廣度和穩(wěn)定性遠(yuǎn)不如今天它的命名體系也偏重嵌入式硬件語(yǔ)境不適合直接照搬到所有項(xiàng)目。但它的機(jī)制骨架——規(guī)則分級(jí)、布局標(biāo)準(zhǔn)化、命名表達(dá)類型、斷言與錯(cuò)誤處理分工、資源回滾、可測(cè)試結(jié)構(gòu)——放到任何 C/C 時(shí)代都成立。我讀這份規(guī)范時(shí)養(yǎng)成的一個(gè)習(xí)慣是把它當(dāng)成編碼前的核對(duì)鏈路先確認(rèn)文件布局與頭文件守衛(wèi)再寫命名與類型再檢查每條控制流分支都有{}再想這個(gè)函數(shù)的失敗路徑怎么回滾最后確認(rèn)斷言只用于內(nèi)部契約。特別是“傳指針必須帶長(zhǎng)度”和“case 分支必須加{}”這兩條幾乎能覆蓋日常 C/C 編碼里一半的越界與作用域事故。從那以后我每次動(dòng)手寫 C/C都會(huì)強(qiáng)制走一遍這條核對(duì)流程單次成本不過(guò)幾分鐘但省下的調(diào)錯(cuò)時(shí)間常常是幾個(gè)晚上。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取