簡(jiǎn)介《中興通訊軟件編程規(guī)范——C/C》是中興通訊2003年發(fā)布的企業(yè)標(biāo)準(zhǔn)主要面向使用C/C的軟件工程師用于統(tǒng)一編碼風(fēng)格、提升代碼質(zhì)量。資源為1個(gè)doc文檔體積約486KB內(nèi)容涵蓋基本原則、布局、注釋、命名規(guī)則、變量常量與類型、表達(dá)式與語(yǔ)句、函數(shù)與過(guò)程、可靠性、可測(cè)試性、斷言與錯(cuò)誤處理等C/C開(kāi)發(fā)的核心環(huán)節(jié)并在附錄A、B中給出了編程模版和規(guī)范檢查表方便在項(xiàng)目中落地執(zhí)行。規(guī)范按規(guī)則性和建議性分類既有必須嚴(yán)格執(zhí)行的規(guī)則也有可根據(jù)項(xiàng)目情況采納的建議并輔以大量正例、反例說(shuō)明其“首先為人編寫程序其次才是計(jì)算機(jī)”的原則對(duì)提高代碼可讀性、可維護(hù)性和減少缺陷很有幫助。已有301人學(xué)習(xí)這份資料適合需要建立或完善編碼規(guī)范的研發(fā)團(tuán)隊(duì)、企業(yè)內(nèi)訓(xùn)和自學(xué)的開(kāi)發(fā)者。1. 先說(shuō)結(jié)論一份2003年的 C/C 編碼規(guī)范最值錢的是那八個(gè)原則接手一個(gè)跑了七八年的通信設(shè)備驅(qū)動(dòng)模塊讓人崩潰的往往不是算法本身而是代碼風(fēng)格有些文件用 Tab有些用空格指針星號(hào)一會(huì)兒在類型后面一會(huì)兒貼在變量名上同一種錯(cuò)誤碼在三個(gè)文件里有三種寫法。某通信設(shè)備廠商 2003 年發(fā)布的這份《軟件編程規(guī)范——C/C》就是為了治這種亂象。它把“為人編寫程序”“先正確性后效率”“避免全局變量”等 8 條原則放在最前后面用 12 個(gè)章節(jié)把布局、注釋、命名、可靠性、可測(cè)試性全部量化成可審核的規(guī)則。適合寫設(shè)備端、驅(qū)動(dòng)、嵌入式協(xié)議?；蛘咭獛F(tuán)隊(duì)收口代碼風(fēng)格的開(kāi)發(fā)者。想減少代碼評(píng)審吵架次數(shù)的人更值得從頭讀一遍。2. 規(guī)范總覽原則、規(guī)則、建議三層結(jié)構(gòu)以及文件布局的硬性要求一份編碼規(guī)范能不能落地不看條目多少看它把約束分成幾個(gè)強(qiáng)度等級(jí)。這份規(guī)范開(kāi)篇先定義術(shù)語(yǔ)再給基本原則然后才展開(kāi)布局、注釋、命名等具體章節(jié)。所有條款被明確分成“原則”“規(guī)則”“建議”三層。原則管思想規(guī)則管行動(dòng)建議留余地。后面十幾章的每一節(jié)基本都按“說(shuō)明、正例、反例”的格式走讀起來(lái)不像法律條文更像一份帶示例的檢查單。2.1 三層約束原則管思想規(guī)則管行動(dòng)建議留余地規(guī)范的總則部分一共 8 條原則很多人只把它當(dāng)作口號(hào)實(shí)際上整份標(biāo)準(zhǔn)的邏輯都從這 8 條長(zhǎng)出來(lái)。第 1 條“首先是為人編寫程序其次才是計(jì)算機(jī)”解釋了為什么要定這么多看起來(lái)瑣碎的布局規(guī)則。第 4 條“編程時(shí)首先達(dá)到正確性其次考慮效率”直接決定了后面可靠性和錯(cuò)誤處理的優(yōu)先級(jí)。第 5 條“避免或少用全局變量”影響的是變量、常量與類型那一章的寫法。第 6 條“盡量避免使用 GOTO”在表達(dá)式與語(yǔ)句、函數(shù)與過(guò)程章節(jié)里都有呼應(yīng)。從這里能看出這套規(guī)范的設(shè)計(jì)思路先統(tǒng)一價(jià)值觀再定操作規(guī)矩。如果把所有規(guī)則平鋪開(kāi)發(fā)者容易陷入“為格式而格式”的誤區(qū)。先講清楚代碼是給人讀的后面的 80 列限制、注釋規(guī)范、命名規(guī)則才立得住。規(guī)則和建議的區(qū)分同樣重要。規(guī)則必須執(zhí)行比如不使用 Tab、{與}獨(dú)占一行、函數(shù)名后不留空格。建議則保留彈性比如某個(gè) switch 分支是否一定要用{}包起來(lái)項(xiàng)目組可以根據(jù)實(shí)際情況決定。落地時(shí)不把規(guī)則和建議混為一談評(píng)審才不會(huì)被細(xì)節(jié)拖垮。2.2 頭文件布局先防重復(fù)包含再排四類聲明規(guī)范第二章“布局”首先規(guī)定的不是縮進(jìn)而是文件布局順序。頭文件要按固定次序書寫文件頭注釋、#ifndef宏定義、其他條件編譯選項(xiàng)、#include然后才是常量定義、全局宏、全局?jǐn)?shù)據(jù)類型、類定義和全局函數(shù)原型最后以#endif收尾。#ifndef DEVICE_MODULE_H #define DEVICE_MODULE_H #include stdio.h /* 標(biāo)準(zhǔn)庫(kù)頭文件用尖括號(hào) */ #include dev_config.h /* 非標(biāo)準(zhǔn)庫(kù)頭文件用雙引號(hào) */ #define MAX_BUF_LEN 128 /* 常量定義 */ typedef unsigned char BOOLEAN; /* 全局?jǐn)?shù)據(jù)類型 */ class CDevice { public: CDevice(void); ~CDevice(void); int GetStatus(void); void SetStatus(int iStatus); private: int m_iStatus; }; #endif代碼里的#ifndef DEVICE_MODULE_H / #define DEVICE_MODULE_H / #endif就是防重復(fù)包含的標(biāo)準(zhǔn)做法。宏名通常取文件名大寫加下劃線避免和其他模塊撞名。#include的次序也有講究標(biāo)準(zhǔn)庫(kù)在前非標(biāo)準(zhǔn)庫(kù)在后這樣自定義頭文件里的依賴錯(cuò)誤會(huì)更快暴露出來(lái)而不是被標(biāo)準(zhǔn)庫(kù)的隱藏包含掩蓋。在這個(gè)布局里常量、宏、數(shù)據(jù)類型、類的順序不能亂。先定義常量再定義依賴這些常量的宏接著定義類型最后定義類。把類的定義放在最靠后的位置保證類能引用前面所有聲明。我一般在新建頭文件時(shí)直接按這個(gè)模板填空比每次重新排布少犯錯(cuò)。2.3 實(shí)現(xiàn)文件布局從包含到函數(shù)體的固定次序?qū)崿F(xiàn)文件的布局同樣有明確順序文件頭注釋、#include、常量定義、文件內(nèi)部使用的宏、內(nèi)部數(shù)據(jù)類型、全局變量、靜態(tài)全局變量、局部函數(shù)原型、類的實(shí)現(xiàn)、全局函數(shù)、局部函數(shù)。#include device_module.h #include string.h #define INTERNAL_MARK 0xAA /* 文件內(nèi)部使用的宏 */ static int s_iInternalTotal 0; /* 靜態(tài)全局變量 */ static int ValidateInput(int iInput); /* 局部函數(shù)原型 */ int DoProcess(int iInput) { int iRet ValidateInput(iInput); if (iRet ! 0) { return iRet; } s_iInternalTotal iInput; return iRet; } static int ValidateInput(int iInput) { if (iInput 0) { return -1; } return 0; }這種順序的本質(zhì)是“先聲明后使用”。局部函數(shù)原型放在文件前面后面實(shí)現(xiàn)順序就可以任意排列不用再擔(dān)心編譯器報(bào)隱式聲明的錯(cuò)。靜態(tài)全局變量集中聲明也方便維護(hù)者一眼看出哪些狀態(tài)被文件內(nèi)部共享。實(shí)現(xiàn)文件還有一個(gè)容易被忽略的點(diǎn)類的實(shí)現(xiàn)放在全局函數(shù)之前。規(guī)范要求構(gòu)造函數(shù)、析構(gòu)函數(shù)、公有函數(shù)、保護(hù)函數(shù)、私有函數(shù)依次實(shí)現(xiàn)和類的聲明順序呼應(yīng)。新人照著這個(gè)順序?qū)戭惔a的可讀性會(huì)高很多。如果實(shí)現(xiàn)文件和頭文件聲明順序不一致查接口定義時(shí)要來(lái)回跳轉(zhuǎn)效率很低。3. 核心規(guī)則拆解布局、注釋、命名里那些一眼能查的硬指標(biāo)布局章節(jié)是整份規(guī)范里最“密”的部分幾乎沒(méi)有廢話。從單行長(zhǎng)度、縮進(jìn)、空行到運(yùn)算符兩側(cè)空格、斷行位置全部給了正例和反例。這些規(guī)則單獨(dú)看像強(qiáng)迫癥合在一起卻構(gòu)成了一套完整的視覺(jué)系統(tǒng)代碼結(jié)構(gòu)通過(guò)縮進(jìn)和空行呈現(xiàn)邏輯邊界通過(guò)換行和括號(hào)表達(dá)。3.1 基礎(chǔ)格式和指針寫法80列、空行、星號(hào)位置規(guī)范要求一行代碼和注釋不超過(guò) 80 列包含空格。這條規(guī)則在今天的高分屏下看顯得保守但如果你需要對(duì)比老舊代碼、在終端里 diff80 列仍然有現(xiàn)實(shí)價(jià)值。另一個(gè)硬規(guī)則是一元操作符前后不加空格二元運(yùn)算符和操作數(shù)之間至少留一個(gè)空格。if (iLen MAX_BUF_LEN) { iResult iLen 1; /* 二元運(yùn)算符兩側(cè)有空格 */ }這里、、兩側(cè)都有空格關(guān)鍵字if和左括號(hào)之間留一個(gè)空格而函數(shù)名和左括號(hào)之間不留空格。視覺(jué)上關(guān)鍵字更突出函數(shù)調(diào)用更緊湊習(xí)慣了之后掃一眼就能區(qū)分if (...)和Function(...)。指針星號(hào)的位置是這個(gè)規(guī)范的一個(gè)特別之處要求*放在變量名前面而不是類型后面。float *pfBuffer; /* 正例星號(hào)靠近變量名 */ float* pfBuffer; /* 反例星號(hào)靠近類型規(guī)范明確反對(duì) */站在 C 語(yǔ)言語(yǔ)法角度*確實(shí)是聲明符的一部分放在變量名前更準(zhǔn)確。比如float *pfBuffer, *pfBuffer2;這種寫法能直接看出兩個(gè)變量都是指針。我見(jiàn)過(guò)很多團(tuán)隊(duì)用float* pfBuffer風(fēng)格也不算錯(cuò)但如果整個(gè)存量工程都按規(guī)范走新代碼就必須跟隨老代碼的風(fēng)格否則會(huì)有刺眼的混排。3.2 對(duì)齊與縮進(jìn)4個(gè)空格、大括號(hào)獨(dú)占一行、等號(hào)排齊規(guī)范明確規(guī)定禁止使用 Tab必須用空格縮進(jìn)縮進(jìn)量為 4 個(gè)空格。{和}獨(dú)占一行并且和引用它們的語(yǔ)句左對(duì)齊。這一條和現(xiàn)代 clang-format 的默認(rèn)風(fēng)格不太一樣更像是 Allman 風(fēng)格。if (iRet 0) { ProcessData(); } else { HandleError(); }大括號(hào)獨(dú)占一行的最大好處是括號(hào)配對(duì)非常直觀尤其在函數(shù)很長(zhǎng)、嵌套很深時(shí)不會(huì)出現(xiàn)}和else粘在一起的情況。代價(jià)是代碼縱向變長(zhǎng)一屏能看到的內(nèi)容變少。這正是規(guī)范里“開(kāi)始講究可讀性”的體現(xiàn)犧牲信息密度換取結(jié)構(gòu)清晰。賦值語(yǔ)句的等號(hào)對(duì)齊屬于容易被忽視的細(xì)節(jié)。規(guī)范要求相關(guān)賦值語(yǔ)句的等號(hào)上下對(duì)齊我實(shí)際用下來(lái)發(fā)現(xiàn)在結(jié)構(gòu)體初始化場(chǎng)景里特別有用tConfig.wHead 0; tConfig.wTail wMaxNum - 1; tConfig.wFree wMaxNum; tConfig.wAddress wConfigAddr; tConfig.wSize wConfigSize;對(duì)齊之后每一行賦值語(yǔ)句處理哪個(gè)字段、值是多少掃一眼就能看出來(lái)。如果不齊讀的時(shí)候需要對(duì)列逐個(gè)比對(duì)增加無(wú)意義的視覺(jué)負(fù)擔(dān)。類似的還有 switch 里的 case 分支建議用{}包起來(lái)避免變量跨 case 意外共享。switch (iCode) { case 1: { DoSomething(); break; } default: { DoNothing(); break; } }每個(gè) case 用括號(hào)隔離能夠防止兩個(gè)分支共享同一個(gè)局部變量也減少了后面補(bǔ)代碼時(shí)不小心把變量聲明到 switch 外的情況。3.3 斷行規(guī)則長(zhǎng)表達(dá)式從低優(yōu)先級(jí)操作符處拆超過(guò) 80 列的表達(dá)式必須斷行規(guī)范給出的原則是從低優(yōu)先級(jí)操作符處拆分操作符放新行之首。比如邏輯與、邏輯或||優(yōu)先級(jí)低于比較運(yùn)算符就應(yīng)該作為斷行的位置。if ((iFormat FORMAT_M) (iOfficeType TYPE_BSC_M)) { DoSomething(); }這里把放在第二行開(kāi)頭閱讀時(shí)會(huì)先看到上一行條件再自然接上第二行條件邏輯流向更清楚。函數(shù)調(diào)用的斷行則在第一個(gè)參數(shù)處對(duì)齊iRet ReportStatusCheckPara(hWnd, ucCallNo, ucStatusReportNo);參數(shù)表逐行排開(kāi)Ctrl 加光標(biāo)可以快速上下移動(dòng)查看每個(gè)參數(shù)。命名一個(gè)最容易踩的坑斷行時(shí)運(yùn)算符留在上一行末尾很多 IDE 的自動(dòng)折行會(huì)這樣處理但規(guī)范明確要求放在新行之首。這是因?yàn)樾惺走\(yùn)算符能提醒讀者“這行是上一行條件的延續(xù)”。3.4 注釋與命名寫意圖而不是復(fù)述代碼注釋部分的核心觀點(diǎn)是注釋要在功能、意圖層次上提供額外信息而不是重復(fù)代碼表面意思。/* 反例這行注釋完全多余 */ iCount; // iCount 加一 /* 正例解釋為什么這里需要加一 */ iCount; /* 補(bǔ)償上次分包丟棄的一幀數(shù)據(jù) */判斷一條注釋是否值得寫可以看刪掉它之后是否損失信息。如果刪掉注釋代碼變得難懂說(shuō)明注釋有價(jià)值如果代碼本身已經(jīng)很清楚注釋就是在制造噪音。規(guī)范還要求注釋符和內(nèi)容之間用一個(gè)空格分隔多行注釋統(tǒng)一用/* */單行注釋用//。命名規(guī)則這部分原文沒(méi)有給出完整清單但從正反例可以明顯看出它采用的是匈牙利前綴風(fēng)格。指針變量用p開(kāi)頭如pfBuffer整型用i如iLen、iCount無(wú)符號(hào)用u字符串用str結(jié)構(gòu)體變量用t前綴如tConfig全局變量用g_靜態(tài)變量用s_成員變量用m_前綴。類名用C開(kāi)頭如CDevice。這種命名在 2003 年的環(huán)境里很有價(jià)值因?yàn)楫?dāng)時(shí)的 IDE 補(bǔ)全能力弱看到名字就知道類型和變量作用域。今天的工程里是否繼續(xù)全量沿用取決于團(tuán)隊(duì)代碼庫(kù)的年齡和工具鏈后面會(huì)專門說(shuō)。4. 可靠性、可測(cè)試性與斷言把錯(cuò)誤擋在上線之前這份規(guī)范的第 10 到第 12 章是整份文檔的精華可靠性、可測(cè)試性、斷言與錯(cuò)誤處理。前面布局和命名規(guī)則決定代碼好不好讀這三章決定代碼能不能少出事故。老團(tuán)隊(duì)愿意把“軟件編程規(guī)范”這份文檔當(dāng)成硬標(biāo)準(zhǔn)很大程度是因?yàn)檫@些章節(jié)里的經(jīng)驗(yàn)都是從線上故障里反推出來(lái)的。4.1 可靠性優(yōu)先先正確后高效再談資源占用可靠性一章的基本思路在總則里已經(jīng)埋下先正確性后健壯性再考慮效率和資源占用。落實(shí)到代碼上常見(jiàn)的處理方式是所有對(duì)外輸入先做合法性檢查所有可能失敗的操作都要有明確定義不能靜默失敗。int InitBuffer(Buffer *ptBuf, int iCapacity) { if (ptBuf NULL) { return -1; } if (iCapacity 0) { return -2; } ptBuf-pData malloc(iCapacity); if (ptBuf-pData NULL) { return -3; } ptBuf-iCapacity iCapacity; ptBuf-iLength 0; return 0; }這種逐層檢查的寫法看起來(lái)過(guò)度防御但是在通信設(shè)備這類長(zhǎng)時(shí)間運(yùn)行、資源受限的場(chǎng)景里任何一處空指針解引用都可能引起整機(jī)重啟。每個(gè)錯(cuò)誤碼-1、-2、-3分別對(duì)應(yīng)空指針、非法容量、內(nèi)存分配失敗調(diào)用方可以根據(jù)返回值做不同處理。規(guī)范鼓勵(lì)這種顯式錯(cuò)誤返回而不是用一個(gè)籠統(tǒng)的false掩蓋全部問(wèn)題。另外需要強(qiáng)調(diào)的是規(guī)范第 5 章“變量、常量與類型”里還有一條相關(guān)要求局部變量必須初始化。常見(jiàn)的內(nèi)存錯(cuò)亂里很大比例來(lái)自未初始化的指針和數(shù)組下標(biāo)。老代碼里經(jīng)常見(jiàn)到聲明了一堆變量然后中間路徑直接返回變量沒(méi)有被賦值而后續(xù)代碼誤以為它已經(jīng)被初始化了。4.2 斷言與錯(cuò)誤處理不變量交給 assert外部異常交給返回值斷言和錯(cuò)誤處理是兩種不同性質(zhì)的機(jī)制很多新人在同一段代碼里混用。規(guī)范的思路是用斷言檢查程序內(nèi)部不該發(fā)生的不變量用錯(cuò)誤碼或返回值處理外部輸入和資源失敗。#include assert.h int SetBufferLength(Buffer *ptBuf, int iLen) { assert(ptBuf ! NULL); /* 內(nèi)部不變量絕不應(yīng)為空 */ assert(iLen 0 iLen ptBuf-iCapacity); if (ptBuf-pData NULL) { return -1; /* 外部條件需要返回錯(cuò)誤 */ } ptBuf-iLength iLen; return 0; }這里assert(ptBuf ! NULL)斷言的是調(diào)用者不可能傳空指針給我如果傳了說(shuō)明調(diào)用方代碼有 bug。斷言在發(fā)布版本里可能被NDEBUG編譯選項(xiàng)刪除所以它不能承擔(dān)錯(cuò)誤處理職責(zé)。而pData NULL是運(yùn)行時(shí)外部條件即使發(fā)生也能通過(guò)返回值讓上層恢復(fù)必須用錯(cuò)誤處理機(jī)制兜底。我在看老項(xiàng)目的代碼時(shí)一個(gè)判斷代碼成熟度的標(biāo)準(zhǔn)就是內(nèi)部接口用斷言外部接口用錯(cuò)誤返回。如果反過(guò)來(lái)在內(nèi)部函數(shù)里把所有不變量都返回錯(cuò)誤碼發(fā)布版本雖然還在檢查但大量無(wú)意義的檢查會(huì)掩蓋真正的關(guān)鍵路徑。如果外部輸入被assert處理發(fā)布版本一旦上線直接放空指針進(jìn)來(lái)程序就裸奔了。4.3 可測(cè)試性習(xí)慣函數(shù)邊界清晰副作用收斂可測(cè)試性章節(jié)的核心要求是最小化外部依賴和全局狀態(tài)。全局變量在這里不僅是耦合問(wèn)題還是測(cè)試失敗時(shí)定位成本的問(wèn)題。一個(gè)函數(shù)直接讀寫全局變量測(cè)試時(shí)想構(gòu)造幾種不同輸入就得先想辦法重置全局狀態(tài)。/* 反例結(jié)果直接寫進(jìn)全局變量 */ int g_iPacketCount 0; void ProcessPacket(const unsigned char *pucBuf, int iLen) { g_iPacketCount iLen; } /* 正例通過(guò)指針把結(jié)果交給調(diào)用方 */ int ProcessPacket(const unsigned char *pucBuf, int iLen, int *piOutCount) { if (pucBuf NULL || iLen 0) { return -1; } *piOutCount iLen; return 0; }正例把函數(shù)設(shè)計(jì)成“輸入?yún)?shù) 輸出參數(shù) 返回值”的標(biāo)準(zhǔn)結(jié)構(gòu)不依賴任何文件級(jí)狀態(tài)。測(cè)試時(shí)只需要準(zhǔn)備輸入和輸出緩沖斷言返回值和輸出即可。規(guī)范在函數(shù)與過(guò)程章節(jié)里也同樣強(qiáng)調(diào)單一職責(zé)、函數(shù)不宜過(guò)長(zhǎng)這兩章合在一起基本就是現(xiàn)代單元測(cè)試的雛形。2003 年還沒(méi)有今天這么成熟的測(cè)試框架但這些思想放到現(xiàn)在完全不過(guò)時(shí)?？蓽y(cè)試的代碼天然容易 review因?yàn)樗迅弊饔脭[在了明面上。5. 落地避坑指南2003年的規(guī)范用進(jìn)今天工程的五個(gè)注意點(diǎn)好的規(guī)范如果不能落地就只是一份漂亮的 PDF。把這份 2003 年的標(biāo)準(zhǔn)引入現(xiàn)代團(tuán)隊(duì)最大的障礙是工具鏈和代碼庫(kù)的現(xiàn)狀。下面這幾個(gè)坑我基本都踩過(guò)寫出來(lái)供參考。5.1 編輯器差異導(dǎo)致縮進(jìn)翻車統(tǒng)一配置不是口號(hào)現(xiàn)象一個(gè)倉(cāng)庫(kù)里有人用 Vim、有人用 VS Code、有人用 Qt Creator明明規(guī)范寫著“禁用 Tab、縮進(jìn) 4 空格”最終提交的代碼仍然出現(xiàn)混排。原因是每個(gè)編輯器的默認(rèn) Tab 寬度不同有的轉(zhuǎn)成空格有的保留 Tab 字符。解決把規(guī)則寫進(jìn).editorconfig讓所有主流 IDE 自動(dòng)讀取再在 Git 鉤子里攔截混合縮進(jìn)。[*.{c,cpp,h}] indent_style space indent_size 4 end_of_line lf這個(gè)配置解決了“新建文件”的問(wèn)題存量文件里的歷史縮進(jìn)問(wèn)題還得靠格式化工具分目錄處理。我一般會(huì)先對(duì)增量代碼強(qiáng)制檢查存量代碼只在改動(dòng)到的函數(shù)內(nèi)順手清理不搞一次性全倉(cāng)格式化否則 diff 會(huì)大得沒(méi)法 review。5.2 匈牙利前綴和現(xiàn)代C風(fēng)格打架現(xiàn)象規(guī)范要求成員變量帶m_前綴、指針帶p前綴但團(tuán)隊(duì)引入現(xiàn)代 C 之后STL 容器、智能指針、模板代碼根本塞不進(jìn)這套命名體系。結(jié)果出現(xiàn)m_iCount和readerIndex_混在一個(gè)文件里的情況風(fēng)格分裂。原因不是規(guī)范的命名思路錯(cuò)了而是它生前的語(yǔ)境是補(bǔ)全能力弱、類型信息藏在名字里的時(shí)代。今天的 IDE 能直接懸浮看到變量類型過(guò)度前綴反而讓名字變長(zhǎng)。解決對(duì)老模塊保留既有匈牙利風(fēng)格保持存量代碼一致性對(duì)新模塊只保留m_成員前綴去掉類型前綴。團(tuán)隊(duì)內(nèi)部明確這條邊界不搞一刀切。代碼評(píng)審時(shí)應(yīng)重點(diǎn)關(guān)注命名是否達(dá)意而不是拘泥于前綴字母。5.3 把規(guī)則和建議混在一起評(píng)審評(píng)論區(qū)當(dāng)場(chǎng)吵起來(lái)現(xiàn)象代碼 review 時(shí)A 說(shuō) switch 的 case 必須用括號(hào)包起來(lái)B 說(shuō)規(guī)范里這只是建議。雙方都有依據(jù)但評(píng)審會(huì)開(kāi)成了辯論賽。原因規(guī)范的普遍分級(jí)沒(méi)有被評(píng)審清單繼承大家對(duì)“建議”到底要不要執(zhí)行沒(méi)有共識(shí)。解決在評(píng)審清單里把規(guī)則分成“必須”和“建議”兩欄必須項(xiàng)納入 CI 檢查建議項(xiàng)只在有明確理由時(shí)才需要討論。我先按規(guī)范附錄 B 的檢查表過(guò)一遍把條目標(biāo)記為強(qiáng)制的才放進(jìn)提交門禁。這樣做之后評(píng)審討論減少了很多無(wú)意義的分歧。5.4 人工檢查容易漏工具掃描要跟上現(xiàn)象人工 review 布局規(guī)范時(shí)總會(huì)漏掉等號(hào)對(duì)齊、運(yùn)算符空格這類細(xì)節(jié)因?yàn)槿四X不擅長(zhǎng)做高頻低難度檢查。原因規(guī)則條目分散在多個(gè)章節(jié)里單靠肉眼逐條對(duì)照效率很低而且容易疲倦。解決把布局規(guī)則和命名基礎(chǔ)規(guī)則轉(zhuǎn)成 clang-format 配置把空指針解引用、資源未釋放等可靠性風(fēng)險(xiǎn)交給 cppcheck 或 clang-tidy。規(guī)范是最好的輸入材料你只需要把規(guī)則逐條翻譯成工具參數(shù)剩下交給 CI 輸出違例文件列表。從附錄 B 的檢查表出發(fā)一張表基本就能映射出一套檢查腳本。5.5 老代碼一次性整改的包袱太大先做增量切換現(xiàn)象團(tuán)隊(duì)想在舊項(xiàng)目里推行規(guī)范有人提議用格式工具全庫(kù)刷一遍結(jié)果生成上萬(wàn)行 diff主干無(wú)法合并其他開(kāi)發(fā)被沖突淹沒(méi)。原因存量代碼不符合規(guī)范是常態(tài)把格式規(guī)范當(dāng)作整容手術(shù)一次做完必然產(chǎn)生巨大成本而且格式 diff 會(huì)掩蓋真正的邏輯改動(dòng)review 形同虛設(shè)。解決采取“增量切換”策略。新代碼從第一天起強(qiáng)制規(guī)范舊代碼只在新功能改動(dòng)時(shí)順手治理。啟動(dòng)階段用 CI 對(duì)新增文件檢查格式和靜態(tài)分析不檢查歷史文件。經(jīng)過(guò)一個(gè)版本周期的治理存量違規(guī)覆蓋率會(huì)明顯下降。我見(jiàn)過(guò)一個(gè)團(tuán)隊(duì)用三個(gè)版本周期把十萬(wàn)行存量代碼的違規(guī)率降到了 10% 以內(nèi)過(guò)程中業(yè)務(wù)迭代沒(méi)有停過(guò)。6. 二次開(kāi)發(fā)把企業(yè)標(biāo)準(zhǔn)剪裁成團(tuán)隊(duì)自己的編碼規(guī)范拿來(lái)即用很誘人但真正有效的落地方式是先做剪裁再轉(zhuǎn)成工具配置最后用數(shù)據(jù)看效果。這套規(guī)范最大的資產(chǎn)是附錄 A 的編程模板和附錄 B 的規(guī)范檢查表二次開(kāi)發(fā)的起點(diǎn)就是這張檢查表。第一步把檢查表逐條過(guò)一遍分類為“強(qiáng)制規(guī)則”“建議規(guī)則”“本團(tuán)隊(duì)不適用的規(guī)則”。比如左括號(hào)換行的 Allman 風(fēng)格如果團(tuán)隊(duì)所有成員都寫 KR 風(fēng)格很多年了不建議強(qiáng)行翻新把“大括號(hào)獨(dú)占一行”降級(jí)為“允許并保持完全一致”。這一步是在做減法不是做加法。第二步把強(qiáng)制規(guī)則映射到工具鏈上。布局和縮進(jìn)由 clang-format 接管命名和可測(cè)性規(guī)則放進(jìn) review 清單。BasedOnStyle: LLVM IndentWidth: 4 UseTab: Never BreakBeforeBraces: Allman PointerAlignment: Right ColumnLimit: 80上面這份 clang-format 配置基本對(duì)應(yīng)規(guī)范里的三條核心布局規(guī)則。這里有一個(gè)常見(jiàn)誤區(qū)生成配置之后要拿幾個(gè)真實(shí)源文件跑一遍看配置和規(guī)范的細(xì)節(jié)是否有沖突。例如 Allman 風(fēng)格會(huì)讓else占一行如果你的團(tuán)隊(duì)不習(xí)慣可以直接關(guān)掉這項(xiàng)不要為了“嚴(yán)格對(duì)標(biāo)”把全員都逼瘋。第三步把檢查表放進(jìn) pre-commit 鉤子只檢查本次提交新增的文件。#!/bin/sh FILES$(git diff --cached --name-only --diff-filterACM -- *.c *.cpp *.h) if [ -n $FILES ]; then clang-format -i $FILES git add $FILES fi這個(gè)鉤子會(huì)在提交前自動(dòng)格式化保證進(jìn)入倉(cāng)庫(kù)的代碼始終符合布局規(guī)則。不過(guò)要注意這里git add $FILES會(huì)把格式化后的文件重新納入暫存區(qū)提交前要確認(rèn)沒(méi)有引入非預(yù)期的改動(dòng)。最后一步是驗(yàn)證。我通?？慈齻€(gè)指標(biāo)代碼評(píng)審里格式類評(píng)論占比、新代碼靜態(tài)檢查違規(guī)數(shù)、單次合并請(qǐng)求的文件改動(dòng)量。這三個(gè)數(shù)字如果持續(xù)下降說(shuō)明規(guī)范已經(jīng)在起作用。從那以后我每次啟動(dòng)新項(xiàng)目都會(huì)先做一次規(guī)范裁剪把強(qiáng)弱規(guī)則寫進(jìn) README再把檢查表轉(zhuǎn)成 CI 腳本最后才讓團(tuán)隊(duì)開(kāi)始寫第一行代碼。這套流程走完新增代碼基本不再需要討論格式問(wèn)題評(píng)審討論集中在真正的邏輯和設(shè)計(jì)上。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取