头文件设计要点:
1、 头文件注释
2、 guard define
3、 尽量不要在头文件中暴露数据结构
4、 要自包含,保证头文件独立编译和功能正确
5、 函数声明前加XXX_API利于拓展
6、 宏的定义
7、 对外提供的头文件放于指定的目录结构
1. 文件头注释
应该加在每个头文件的顶部,必须包含版权许可、功能说明、作者和创建日期。
例如:
a) /*
b) * Copyright (c) Huawei Technologies Co., Ltd. XXXX. All rights reserved.
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"
4)
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
4)
5) LUA_API lua_State *lua_open (void);
下面是外部使用的例子:
6) #ifndef LUA_H
7) #define LUA_H
8) #endif
9)
10)LUA_H lua_State *lua_close (void);
6. 宏的定义时,尽量使用括号来包住所定义的对象
i. 宏定义嵌入某个表达式使用,用括号将其包住。此方法如果用于语句环境将会出语法错误
1) #define LUA_TNONE (-1)
2)
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,很简洁