★ FEATURED ARTICLE 简介中兴通讯软件编程规范C/C是深圳市中兴通讯股份有限公司于2003年发布并实施的企业设计技术标准主要面向使用C/C语言进行产品软件开发的工程师与技术管理者用于统一编码风格解决代码可读性差、命名随意、函数耦合度高、错误处理不统一等团队开发常见问题。规范分为规则性与建议性两类规则性条款要求严格执行。内容覆盖基本原则、代码布局、注释写法、命名规则、变量常量与类型、表达式与语句、函数与过程、可靠性、可测试性、断言与错误处理等章节不仅给出要求还配有大量正例、反例和说明帮助理解“应该怎样写”与“为什么不这样写”附录另附编程模板和规范检查表便于项目组直接落地执行也可作为代码走查的评分依据。压缩包共1个doc文档大小486KB以单文档形式完整收录了这份企业标准。资源已有301人浏览学习适合需要建立C/C编码规范、开展代码质量培训或进行代码评审的软件开发团队参考。1. 为什么一份 2003 年的 C/C 编码规范值得今天再拆一遍“能编译通过”很多时候是假象。C/C 的不少高危写法——悬空的 else、跨 case 的变量声明、裸指针加无长度参数——编译器不报错只在运行时以崩溃或数据错乱的方式兑现后果。某通信设备制造企业早早在 2003 年发布并实施了内部标准《软件编程规范 — C/C》把布局、注释、命名、可靠性、可测试性、断言与错误处理拆成了几十条可执行的条款并要求此后所有新写代码一律遵循。这份规范今天拆开看并不陈旧因为它锁定的全是 C/C 编译器不会替你查、但事故却总爱去的地方。理解它为什么这样设计等于看懂一个成熟的工业团队如何在编译器之外建立第二道防线。2. 规则体系与布局排版如何变成工程能力的底层机制2.1 原则、规则与建议三级约束的“执行弹性”机制规范开篇就定义了三种条款等级原则、规则、建议。原则是“编程时应该坚持的指导思想”比如原则 1-1“首先是为人编写程序其次才是计算机”规则是“编程时必须遵守的约定”建议是“编程时必须加以考虑的约定”。这个三级体系不是文档排版的花架子它解决的是一个实际治理问题一份要覆盖多个产品线、多种嵌入式平台和不同项目节奏的内部标准若所有条款都写成“必须”那在性能敏感或资源受限的模块里就注定会出现大量豁免。豁免一旦形成惯例标准整体就失去约束力。因此文档用“规则”锁死那些破坏后有明确负面后果的做法例如不加{}的单行 if、不用头文件守卫用“建议”保留那些破坏后只是可读性下降的写法例如变量摆放顺序、注释密度。把这一层想清楚能解释后续很多条文的语气差异。比如“避免或少用全局变量”是原则级表述因为它不是“绝对禁止”而是权衡后的方向但“禁止使用 TAB 键必须使用空格缩进”写成了规则因为 TAB 在不同编辑器里宽度不一致会直接破坏所有成员看到同一份代码的视觉基础。机制上这套分级相当于给每个条款配了不同的执行强度让规范既能守住底线又不至于在特殊场景下自废武功。原则的排序同样有深意。“编程时首先达到正确性其次考虑效率”被列在可靠性章节之前等于提前声明了后续所有防御性条款的优先级。C/C 项目的线上事故大多发生在边界路径而不是主路径的热点代码上所以先保证逻辑正确、资源不泄漏、输入有校验再去谈微优化。这一点也解释了为什么规范敢要求检查外部输入、关注边界条件——这些开销在正确性面前都被视为必要成本。2.2 头文件与实现文件的固定“目录”让依赖关系一眼可见规范分别给头文件和实现文件规定了固定的书写次序。头文件依次是文件头注释、#ifndef防重复包含宏、标准库#include、非标准库#include、常量定义、全局宏、全局数据类型、类定义与模板、函数原型、#endif。实现文件则从文件头注释开始依次是#include、常量、文件内宏、文件内数据类型、静态全局变量、局部函数原型、类实现、全局函数与局部函数。注意实现文件里反复出现“文件内”三个字它要求不对外暴露的符号尽量用static或匿名命名空间收束在编译单元内。这个固定目录的收益在工程上是双重的。第一重是阅读秩序任何接手代码的人翻一个文件十分钟就能知道哪里找类型、哪里找宏、哪里找函数实现不用靠经验猜。第二重是依赖显性化头文件的#include列表就是对外接口的依赖清单实现文件的#include列表则是内部实现的依赖清单。两者被格式强制分开后审代码的人一眼能看出接口层是否悄悄混入了实现细节——例如一个头文件里包含了只在 .c 文件里才需要的内部头文件这就是依赖污染的信号。防重复包含的机制值得单独展开。规范给出的正例是#ifndef MODULE_H #define MODULE_H /* 文件体 */ #endif#ifndef到#endif构成一个条件编译块。第一次包含该头文件时MODULE_H未定义预处理器进入文件体并顺手定义MODULE_H第二次再包含时MODULE_H已存在预处理器跳过整个文件体。这就是宏名充当“已包含标记”的原理。正因为机制依赖宏名的全局唯一性规范要求守卫宏用文件名全大写来命名避免两个头文件因守卫同名而互相误伤——第二个文件会被当成“已经包含”而静默跳过于是它的声明整体缺失随后就是报错或者更难查的隐式声明。2.3 缩进、括号与空格排版规则里的语法级理由布局章节的硬性规则细看几乎每条都有语言或工具的根因。“禁止使用 TAB缩进为 4 个空格”根因是 TAB 的渲染宽度取决于编辑器设置同一文件在不同环境下会显示成不同错位而空格是唯一在所有编辑器里宽度一致的字符。缩进幅度定为 4 格也经过权衡2 格在深层嵌套时会糊成一片8 格在函数套函数时迅速把行宽挤爆4 格是阅读密度和行宽消耗的均衡点。“if、else、for、while 等语句自占一行执行语句不得紧跟其后不论执行语句有多少都要加{}”这条同样有明确语法背景。C 系语言的 else 遵循就近匹配不加大括号时一旦有人日后在 if 和 else 之间插入一行语句else 的归属就可能悄悄改变。规范给出的反例是if (varible1 varible2) varible1 varible2;正例里则把执行语句放进花括号if (varible1 varible2) { varible1 varible2; }加花括号的直接效果是把分支边界从文字层面固定下来后期增删语句都不会改变控制流结构。规则还规定{和}独占一行并与引用它们的语句左对齐这让嵌套层级在视觉上变成清晰的垂直折线匹配括号、做代码折叠、排查漏写}都容易得多。指针声明*的位置规范给出了明确主张float *pfBuffer; /* 规范写法 */ float* pfBuffer; /* 反例 */这条看似是风格之争实际是语法结构之争。C/C 声明语法里*属于声明符修饰的是变量名而非类型名。把*紧贴类型写成float* pA, pB;视觉上会诱导人认为pB也是指针但语法上pB只是 float。规范要求的写法则让每个变量前的*单独显形多变量声明时谁是指针一目了然。运算符空格规则也是为同一目的服务一元操作符如!、~、、--前后不加空格多元运算符与操作数之间至少留一个空格关键字后要留空格而函数名后不要。这套规则的本质是制造视觉语法分类器——看到for (i...)知道是控制结构看到Foo(...)知道是函数调用看到a b知道是算术表达式。“(向后紧跟、)、,,; 向前紧跟”这些细规则把复杂表达式里的括号和分隔符变成紧贴结构减少阅读时把括号看作多层嵌套的心理负担。2.4 注释的分层在意图层写作而不是翻译代码规范对注释的定位非常明确注释的价值在于提供代码表面之外的额外信息例如功能意图、设计约束、调用约定而不是把i解释成“i 加一”。这背后是对维护成本的判断——代码是给编译器读的注释是给下一个维护者读的。逐行翻译式注释没有任何信息增量真正有意义的是“为什么这样写”“有什么前置条件”“在哪种场景下会失效”。规范把注释格式也做了统一多行注释用/* ... */单行注释用// ...注释符与内容之间留一个空格文件头要有标识功能、作者意图的注释块。这些细节放在一起形成一种可预期的“注释节奏”阅读代码时注释不会干扰语句结构但会在关键节点给出背景。结合布局规则看注释块同时承担“分隔节”的作用——用规范的注释块把常量定义、类型定义、函数原型各自圈出来等于在代码文件里建立了章节导航。3. 命名、注释与类型编译器看不见的语义契约3.1 匈牙利命名法把类型信息住进标识符规范示例里大量出现iLength、pfBuffer、aiNumbers、strCaption、wHead、ucCallNo、m_iCount、tPDBRes这类名字这是典型的匈牙利命名法。前缀承担类型语义i表示整型f表示浮点w表示 16 位字长uc表示 unsigned charstr表示字符串p表示指针ai表示整型数组m_表示类成员t表示结构体类型。在 2003 年的开发环境里这套前缀体系几乎是“移动端类型提示”。当时没有今天这么成熟的代码跳转和悬浮类型信息看一个函数体时变量类型主要靠声明位置和命名推断。pfBuffer五个字符直接告诉你“这是 float 指针、指向一块缓冲区”不用回头翻声明wAddress直接提示 16 位宽度的寄存器值。这类信息对长代码维护极其有价值尤其是通信设备上大量与硬件寄存器、协议字段打交道的代码类型宽度本身就是业务语义的一部分。更实际的机制收益是可检索性。成员变量统一m_前缀审查者可以用正则把整个文件的成员访问全部筛出来全局变量如果统一前缀代码评审时可以快速排查跨模块耦合。规范另外要求类名以大写字母开头如CCount、常量全大写、函数名用动词性短语这些约定合并起来让“按名字检索”成为可靠的代码导航手段。当代 IDE 弱化了一部分前缀需求但指针、数组、句柄这些易错类型上保留前缀仍然是降低误读成本的有效做法。3.2 常量与类型的边界宏、const、typedef 与全局变量的取舍变量、常量与类型章节的核心约束是控制“状态的可见范围”。全局变量被列为“避免或少用”因为全局状态天然跨模块可见任何函数都能读写任何时序都可能依赖它模块边界被隐式穿透。规范给出的缓解办法也符合模块化机制把全局变量收进实现文件的文件作用域用static限定让它在编译单元内部可见但对外不可见外部模块要访问只能通过函数接口这样依赖关系被显式化。类型定义层面规范示例中的typedef unsigned char BOOLEAN;很有代表性。接口层用BOOLEAN而不是赤裸裸的unsigned char好处有两层一是语义清晰看到BOOLEAN就知道这是布尔逻辑而不是字节运算二是可替换性将来底层要改成int或其他表示时只改一处typedef。这类类型抽象在通信协议代码里尤其重要——协议字段的字节序、位宽、有无符号集中定义后不容易在多处各自走样。常量定义同样有选择问题。规范更看重集中定义和全大写命名但没有把#define一棍子打死。在 C 语言里#define宏不参与类型检查展开阶段直接做文本替换容易带来类型隐患const修饰符则有类型语义能被编译器检查。规范的精神接近于“尽量用编译器可检查的手段表达常量”同时对宏的副作用保持警惕——例如宏参数不写括号导致的优先级问题也是经典翻车点。3.3 表达式与控制语句把歧义消灭在结构层表达式与控制语句章节把许多“编译器允许但语义危险”的写法做了显式约束。if、for、while关键字后留空格再跟左括号函数名后紧跟左括号不留空格这条规则制造了控制关键字与函数调用在视觉上的区分。更细的规则是(向后紧跟、)和,向前紧跟、逗号后留空格——这样写for (i 0; i MAX_BSC_NUM; i) { DoSomething(iWidth, iHeight); }阅读者扫一眼就能判断for是循环、DoSomething是调用不会被括号的排版干扰。条件表达式的续行要求“在第一个条件处对齐”函数调用的续行要求“在第一个参数处对齐”赋值语句续行要求“在赋值号处对齐”这些都让多行表达式保持单一视觉锚点不会因为换行产生歧义。switch 语句的规则值得单独强调。规范要求每个 case 分支和 default 都用{}括起来例如switch (iCode) { case 1: { DoSomething(); break; } case 2: { DoOtherThing(); break; } default: { DoNothing(); break; } }深层原因是 C 的作用域规则case 标签本身不建立作用域块。若在 case 分支里直接声明变量而不加{}该变量会跨越整个 switch 作用域可见其他分支跳转过来时就会跨越初始化点触发编译错误或未定义行为。加上{}后每个分支成为独立作用域变量声明被局限在本分支内跳转逻辑也被结构化。这条规则本质上是把“语言默认的危险行为”通过排版改成“结构上安全的行为”。4. 可靠性、断言与可测试性把故障在发布前逼出来4.1 可靠性条款输入校验与资源回滚机制可靠性章节是这个规范里信息密度最高的地方它针对 C/C 最常见的三类运行时事故——非法输入、越界访问、资源泄漏——分别立规。凡是外部输入进入函数边界时就要做合法性检查凡是接收缓冲区调用方要同时传入长度凡是申请了资源就必须有对应的释放路径。这些条款在嵌入式通信设备上尤其关键因为设备长期在线运行一次内存泄漏或一次越界写都可能累积成不可恢复的系统故障。资源管理的规则最能体现“成对出现”的机制思想。规范要求资源的申请与释放在清晰的模块边界内成对分配失败时已经申请的资源要全部回滚。落到代码上典型的实现是逐级回退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; }这里的可靠性机制是“失败路径逆序清理”。每新增一个资源就新增一个失败出口某个资源申请失败时之前成功的资源沿相反顺序逐个释放。审查者核对这段代码时只需要把申请顺序倒过来对照释放顺序就能判断是否存在泄漏路径。相比把所有free集中在函数末尾的写法逐级回退的优点是职责就近资源生命周期一目了然不会因为中间加了分支而漏掉某条路径的清理动作。4.2 断言与错误处理分清楚“必崩”和“可恢复”断言章节和错误处理章节被规范放在一起这本身就是一种机制设计二者是分工关系不是替代关系。断言应该用来捕获“程序员的错误”——内部不变量被破坏、指针不该为空却为空、状态不该出现却出现了错误处理则用来应对“外部世界的错误”——用户输入非法、网络报文截断、设备返回异常。把二者分开等于给代码定了一条契约边界断言崩在开发期让开发者立刻知道逻辑错了错误处理撑在运行期让程序对外部异常保持降级能力。实现层的关键是断言的可裁剪性。典型的断言库会用NDEBUG宏控制#ifndef NDEBUG #define assert(expr) ((expr) ? (void)0 : abort()) #else #define assert(expr) ((void)0) #endif发布构建里定义NDEBUG后断言调用变成空操作不产生任何运行时开销。这个机制带来一个必须遵守的推论断言不能承担任何“正常流程可能失败”的检查。比如输入参数是否为空指针如果这是外部输入就绝不能靠assert(pData ! NULL)拦截因为它会在发布版里被剥掉非法指针继续往下走故障以更隐蔽的方式爆掉。正确的姿势是:assert(pData ! NULL); /* 契约内部逻辑保证这里非空 */ if (pData NULL) { /* 防御外部输入可能有误 */ return ERROR_INVALID_PARAM; }断言表达“这里不该出错”if表达“这里出错很正常”。一旦把二者混用要么发布版失去保护要么正常业务错误直接触发进程终止。规范里还有一个易被忽略的细节函数原型要求写int Foo(void)而不是int Foo()。在旧式 C 语法里int Foo()表示“参数类型未定义”编译器不做实参校验int Foo(void)才是“不接受任何参数”的明确声明。写清楚void等于消掉了一类未定义行为的歧义。4.3 可测试性让故障可观测的源码结构可测试性章节关心的是当故障真的发生时代码结构能不能帮人快速定位。规范给出的路径是函数单一职责、控制参数个数、避免函数内部大量隐式依赖全局状态。单一职责函数的收益在测试层面非常直接输入可构造、输出可断言、副作用可控制。如果一个函数同时负责解析报文、修改全局表、写日志、触发消息那任何输入组合的验证都会牵动多个模块故障定位也无从下手。与可测试性配套的是信息封装规则。规范要求实现文件把不对外暴露的函数、变量收进文件内只暴露必要接口这让测试目标明确被测试的是公开接口内部结构可以在不破坏契约的前提下重构。同时错误路径必须通过返回值或显式错误码表达而不是靠全局标志位。把这几点合并起来看可测试性章节的底层逻辑是任何故障都应该能被观测任何观测都应能定位到函数。这与现代可观测性思想同源只是 2003 年它把“可观测”落实在源码的组织纪律上而不是日志与监控平台。5. 避坑实录执行编码规范时绕不开的 5 个现场5.1 头文件守卫写了还是出现重定义现象两个模块都写了#ifndef MODULE_H单独编译各自正常联合编译时却出现类型或宏重复定义。原因守卫宏的作用域是整个编译单元。两个不同头文件用了同一个宏名时第二个头文件的#ifndef条件不成立整个文件体被预处理器跳过等于“声明从未发生过”而其他源文件各自包含它们后外部符号定义又按某种顺序暴露出来于是出现重定义或声明缺失的交替报错。这个坑的根源是守卫宏依赖全局唯一命名仅靠“守卫存在”并不足以保证正确。解决守卫宏必须与文件名唯一对应并加上工程前缀例如#ifndef MODULE_H改成#ifndef ZX_MODULE_H之类的唯一形态同时把#endif放在文件最末不在守卫内混入多余的代码。提交前用脚本扫描所有头文件检查守卫名与文件名是否一一对应可以把这个坑彻底封死。5.2 缩进看着对齐换个编辑器全部错位现象代码在自己编辑器里整整齐齐推到另一台机器或 CI 差异视图里花括号、注释、续行全部错位甚至让人误判嵌套关系。原因代码里有真实存在的 TAB 字符。TAB 的渲染宽度取决于编辑器默认值有的按 4 格有的按 8 格有的按“对齐到下一个制表位”于是同一字符在不同环境显示成不同宽度。缩进一旦错位“视觉对齐”这个机制就失效了嵌套层级的判断靠肉眼必然出错。解决严格按规范的“禁止 TAB、缩进 4 空格”执行。把编辑器设置成输入 TAB 时自动替换为空格同时在代码仓库的提交钩子里加一道检查凡是文件里出现\t字符就直接拦截。这类格式化约束在多人协作里不是审美问题是跨环境一致性的地基。5.3 指针声明写成float*一行声明两个变量时埋雷现象某处写了float* pA, pB;后续维护者把pB当指针使用传入函数后发生非法访问崩溃现场还看不出类型问题。原因语法层面*绑定的是声明符变量名不绑定类型符。float* pA, pB中pA是指针pB是 float。把*紧贴类型会让阅读者的视觉类型判断与语法的实际类型不一致。视觉判断一旦与语法不符后续使用就容易踩线。解决按规范把*放在变量名前写成float *pA, *pB;。它虽然写起来长一点但每个变量名身旁的*都在各自声明里独立归属谁是指针清清楚楚。更进一步多指针声明尽量拆成多行让每个声明自带完整上下文误读概率才会真正降下来。5.4 switch 的 case 里声明变量编译报“跨初始化跳转”现象case 分支里直接写int iValue 0;打开高警告级别编译后报错内容涉及 “crosses initialization”但加{}后消失。原因case 标签本身不建立作用域块。直接声明变量时这个变量被提升到整个 switch 上下文其他 case 分支的跳转路径会“跨过”这个变量的初始化语句而 C 规则禁止跳过带非平凡初始化的变量声明所以编译器亮红灯。这不是警告而是硬错误但根因容易被人误读成“编译器抽风”。解决按规范给每个 case 分支加{}把变量声明关进独立作用域。这样每个分支自成一体跳转不再跨越初始化点。实践里这还会顺手解决另一个问题case 分支之间不写break导致的贯穿执行在{}结构下更容易被肉眼发现。5.5 断言和错误处理混用线上程序被 assert 打崩现象发布版本收到崩溃报告栈顶停在断言行查代码发现断言是用来拦截“用户输入非法”的。原因发布构建通常定义NDEBUG断言调用会被整个编译掉但有些团队的发布构建没有统一关断言或者更常见的是工程师把断言当成了参数校验手段在 debug 构建里一切正常发布构建里断言消失后非法输入长驱直入故障以更隐蔽的方式爆出来。解决断言只负责内部不变量外部输入校验一律走错误码或显式的条件分支。发布构建统一编译选项明确禁用断言关键业务路径上对失败要记录日志而不是静默。要把“这是外部世界可能带来的错误”和“这是程序内部不该发生的错误”这两类判断写进代码评审的标准里而不是依赖某一个人当时的状态。6. 取舍与演进规范给你的是底线不是标准答案回看这份规范最值得琢磨的不是某一条规则的正误而是它作为一个整体展现出的取舍逻辑。第一组取舍是“统一性”与“差异性”。它用规则/建议分级来平衡破坏后会产生系统性故障的写进规则破坏后只是不好看的放进建议。今天复刻这套思路时更高效的路径是反着来——先把所有“建议级”条目交给格式化工具和 CI 校验去执行再把人工评审的注意力集中在“规则级”的可靠性、断言边界、命名语义上。2003 年没有自动格式化缩进对齐只能靠人脑执行今天的工具链已经把这些变成零成本真正贵的是让工程师把“工具查不出的约定”内化成习惯。第二组取舍是“正确性优先”与“效率灵活性”。原则 1-4 排好了序正确性先于效率。这不只是口号它支撑着后续所有防御性条款的成立。通信设备这类长生命周期产品代码交付后要在线运行数年维护成本远高于开发成本一次线上内存越界或资源泄漏可能需要排查几周。规范选择在开发阶段付出少量检查开销换取运行阶段的事故概率下降这本质上是用前置约束换后期自由。要清醒地看到这份规范的年代局限。它没有涉及异常安全、RAII 资源管理这些现代 C 特性因为 2003 年的主流编译器对模板和异常支持的广度和稳定性远不如今天它的命名体系也偏重嵌入式硬件语境不适合直接照搬到所有项目。但它的机制骨架——规则分级、布局标准化、命名表达类型、断言与错误处理分工、资源回滚、可测试结构——放到任何 C/C 时代都成立。我读这份规范时养成的一个习惯是把它当成编码前的核对链路先确认文件布局与头文件守卫再写命名与类型再检查每条控制流分支都有{}再想这个函数的失败路径怎么回滚最后确认断言只用于内部契约。特别是“传指针必须带长度”和“case 分支必须加{}”这两条几乎能覆盖日常 C/C 编码里一半的越界与作用域事故。从那以后我每次动手写 C/C都会强制走一遍这条核对流程单次成本不过几分钟但省下的调错时间常常是几个晚上。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
