编程规范

 

编程规范

1头文件

放置接口不放置实现

• 头文件只放置对外接口的声明(函数声明、宏定义、类型定义)，内部使用的这些声明不应该放在头文件中
• 变量定义在c文件中，尽量不要使用全局变量作为接口，应通过函数来作为接口。若要使用全局变量，应在c文件中定义，h文件中声明

职责应单一

• 头文件不应包含过多头文件，职责应尽量单一

向稳定方向包含

• 不稳定的模块依赖稳定的模块，当不稳定模块发生变化时不会影响稳定的模块
• 产品依赖于平台，平台依赖于标准库
• 更好的方式是多个模块共同依赖于接口，增强低耦合性

规则

• .c对应.h，用于声明对外公开的接口
• 禁止头文件循环依赖
• .c.h禁止包含用不到的头文件
• .h中添加#define保护
• .h禁止定义变量
• 使用接口只能通过包含头文件实现，禁止使用extern
• 禁止在extern "C"中包含头文件，会有bug

建议

• 一个模块内的多个c文件放在同一个目录，一个模块提供一个.h来整合模块对外接口
• 包含头文件按照固定规则排序(升序，稳定性排序)

2函数

一个函数一个功能

重复的代码提炼成函数

规则

• 函数不能过长，不超过50行(非空非注释)
• 嵌套不超过四层
• 可重入函数避免使用共享变量；应通过互斥信号等方式保护
• 参数合法性的检查，统一成调用负责或者接口负责
• 执行结果不同返回特定码
• 高扇入，合理扇出(小于7)；被调用的多，调用的接口数目合理
• 废弃代码(未调用的函数和变量)及时清除
• 不变形参加const修饰
• 函数避免使用全局变量、静态局部变量，不可避免的地方应集中使用
• 检查非参数输入的有效性，公共变量等
• 形参不超过5个
• 除打印类函数，不要使用可变长参函数
• 源文件中声明定义的内部函数，应用static修饰

3标识符命名和定义

通用命名规则

• unix风格：单词使用小写字母，中间用_分割
• window风格：单词连在一起，单词首字母大写

命名有明确含义，使用完整的单词或大家都能理解的缩写

除通用缩写外，若有专用缩写应在注释或某处做统一说明

建议

• 若非必要，名字中不要出现数字编号
• 标识符前不应添加模块、项目、产品、部门的名称做前缀

文件命名规则

• 统一采用小写字符

变量命名规则

• 全局变量加"g_"前缀
• 静态变量加"s_"前缀
• 禁止使用单字节命名变量，允许i,j,k作为局部循环变量
• 使用名词或者形容词+名词方式命名变量

函数命名规则

• 以函数要执行的动作命名，一般采用动词或者动词+名词的结构
• 函数指针除了前缀，其他按照函数的命名规则命名

宏的命名规则

• 对于数值或者字符串等等常量的定义，建议采用全大写字母，单词间加_的方式命名，枚举同样建议
• 除头文件或编译开关等特殊标识定义，宏定义不能使用_开头和结尾

4变量

一个变量只有一个功能

结构应功能单一，不要设计面面俱到的数据结构

不用或者少用全局变量

• 单个文件内可以使用static的全局变量

规则

• 防止局部变量和全局变量同名
• 通信过程中使用的结构要注意字节顺序
• 严禁未经初始化的变量作为右值

建议

• 构造仅有一个模块或函数可以修改、创建，而其余有关模块或函数只访问的全局变量，放置多个不同模块或函数都可以修改、创建统一全局变量的现象
• 使用面向接口编程思想，通过API访问数据：如果本模块的数据需要对外部模块开放，应提供接口函数来设置、获取，同时注意全局数据的访问互斥
• 首次使用前初始化变量，初始化的地方离使用的地方越近越好
• 明确全局变量的初始化顺序，避免跨模块的初始化依赖
• 尽量减少没有必要的数据类型默认转换与强制转换

5宏、常量

规则

• 用宏定义表达式时，要使用完备的括号
• 将宏所定义的多条表达式放在大括号中
• 使用宏时，不允许参数发生变化
• 除非必要，应可能使用函数代替宏
• 常量建议使用const定义代替宏
• 宏定义中尽量不适用return,goto,continue,break等改变程序流程的语句

6注释

优秀的代码可以自我解释，不通过注释就可轻易读懂

注释的内容要清楚、明了，含义准确，放置注释二义性

在代码的功能、意图层次上进行注释，即注释解释代码难以直接表达的意图，而不是重复描述代码

规则

• 修改代码时，维护代码周边的所有注释，以保证注释与代码的一致性。不再有用的注释要删除
• 文件头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者姓名、内容、功能说明、与其他文件的关系、修改日志等，头部的注释中还应该有函数功能简要说明
• 注释应放在其代码上方相邻位置或右方，不可放在下方
• 对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完，下一个case语句前加上明确的注释
• 避免在注释中使用缩写，除非是通用的缩写

7排版和格式

规则

• 程序块采用缩进风格编写，每级缩进为4个空格
• 相对独立的程序块之间、变量说明之后必须加空行
• 一条语句不能过长，如不能拆分需要分行写
• 多个短语句(包括赋值语句)不允许写在同一行内，即一行只写一条语句
• if,for,do,while,case,switch,default等语句独占一行
• 在两个以上的关键字、变量、常量进行对等操作时，他们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果时关系密切的立即操作符（->），后不应加空格
• 注释符与注释内容之间要用一个空格进行分割