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