专业的C头文件设计和重构指南

头文件设计要点：

1、头文件注释

2、 guard define

3、尽量不要在头文件中暴露数据结构

4、要自包含，保证头文件独立编译和功能正确

5、函数声明前加XXX_API利于拓展

6、宏的定义

7、对外提供的头文件放于指定的目录结构

1. 文件头注释

应该加在每个头文件的顶部，必须包含版权许可、功能说明、作者和创建日期。

例如:

a) /*

c) * Description: 文件功能描述

d) * Author: 王二

e) * Create: 2012-12-22

f) */

2. guard define

整个头文件应该在guard define之间, 为防止头文件被多重包含，所有头文件都应当使用 #define 作为包含保护；

定义包含保护符时，应该遵守如下规则：

ü 保护符使用唯一名称；

ü 建议考虑项目源代码树顶层以下的文件路径不要在受保护部分的前后放置代码或者注释，文件头注释除外。

假定 VOS 工程的 timer 模块的 timer.h，其目录为 vos/include/timer.h 。其保护符若使用 'TIME_H' 很容易不唯一，所以使用项目源代码树的全路径，如：

如：

1) #ifndef VOS_INCLUDE_TIMER_H

2) #define VOS_INCLUDE_TIMER_H

3) //声明对外的接口

4) #endif

另外，如果这个头文件可能给c++使用，要加上

1) #ifdef __cplusplus

2) extern "C" {

3) #endif

4) //声明对外的接口

5) #ifdef __cplusplus

6) }

7) #endif
注：禁止在 extern "C" 中包含头文件

3. 尽量不要在头文件中暴露数据结构

这样可以用户降低对你的实现的依赖，也减少了用户的编译时间

1) typedef struct lua_State lua_State;

2) LUA_API lua_State *lua_open (void);

3) LUA_API void lua_close (lua_State *L);

可以看到虽然用户会一直使用lua_State,但是并不知道lua_State的结构是什么

从一个使用lua的例子程序可以看出：

1) #include "lua.h"

2) #include "lauxlib.h"

3) #include "lualib.h"

5) int main(int argc, char *argv[])

6) {

7) lua_State *L = lua_open();

8) const char *buf = "var = 100";

9) int var ;

10) luaopen_base(L);

11) luaopen_io(L);

12) lua_dostring(L, buf);

13) lua_getglobal(L, "var");

14) var = lua_tonumber(L, -1);

15) lua_close(L);

16) return 0;

17)}

4. 要自包含，保证头文件独立编译和功能正确

i. 能独立编译

要保证本头文件在任何使用场景下，都能独立编译。其中，相对路径引入就是一个案例。如：

#include <comm_type.h>不是标准库情况下，可能无法引入相关文件，可改成：

#include “../../XXX/XXX/ comm_type.h”

ii. 对外提供功能正确

头文件能独立编译了，但不一定能对外提供的功能是正确的。对外提供的功能可能还需要代码适配，以保证功能正确。

5. 下面是一个私有宏暴露给模块外部，致使相关模块使用时能编译通过，但功能却不正确。

解决办法就是不要暴露数据本身，通过接口反馈给外部模块数据值即可。（这个问题，也是尽量不要在头文件中暴露数据结构的一个典型案例）

案例：

1) 功能失败点，从图1看到rsaM.Datalen = RSA_LEN,再从图2看到RSA_LEN != pData->dataLen的应该是相等，但实际结果却是错误的，这就是问题暴露点

图1

图2

2) 继续追查RSA_LEN，它是RSA_KEY_LEN的重定义，见图3。而从图4可以看出RSA_KEY_LEN的值由一个开关控制，编译环境不一样，值不同

图3

图4

3) 问题在于本模块对外提供能力时，没有考虑到编译环境的要求，应用方也没有明白这点，应用方无法掌控这个宏的编译环境，从而无法得到正确值引发了这个问题。解决办法就是通过接口对外提供值，而不是数据结构本身。

5. 函数声明前加XXX_API利于拓展

iii. Lua的例子，如果定义了LUA_API就是给LUA内部使用的，如果没定义LUA_API就是for user的

下面是内部使用的例子：

1) #ifndef LUA_API

2) #define LUA_API

3) #endif

5) LUA_API lua_State *lua_open (void);

下面是外部使用的例子：

6) #ifndef LUA_H

7) #define LUA_H

8) #endif

10)LUA_H lua_State *lua_close (void);

6. 宏的定义时，尽量使用括号来包住所定义的对象

i. 宏定义嵌入某个表达式使用，用括号将其包住。此方法如果用于语句环境将会出语法错误

1) #define LUA_TNONE (-1)

3) #define lua_register(L,n,f) \

4) (lua_pushstring(L, n), \

5) lua_pushcfunction(L, f), \

6) lua_settable(L, LUA_GLOBALSINDEX))

ii. 宏定义当语句使用，用do while(0)将其包住。此方法如果用于表达式环境将会出语法错误

7) #define DOSOMETHING () \

8) do{

9) foo1();

10) foo2();

11) }while(0)

7. 对外提供的头文件放于指定的目录结构

一般应该使用一个单独的include目录来包含要发布的头文件，但不应该把内部使用的头文件包含进去。例如：Lua的include目录只包含了三个头文件lauxlib.h , lua.h, lualib.h，很简洁

巴特西

专业的C头文件设计和重构指南

最新文章

热门文章