如何寫出專業的頭文件

做到專業，應該是每個職業程序員應該要求自己做到的。
讓我們看看lua是怎麼寫頭文件的。

1.License Agreement
License Agreement應該加在每個頭文件的頂部。
Lua Sample:

 

/*
** $Id: lua.h,v 1.175b 2003/03/18 12:31:39 roberto Exp $
** Lua - An Extensible Extension Language
** Tecgraf: Computer Graphics Technology Group, PUC-Rio, Brazil
** http://www.lua.org    mailto:[email protected]
** See Copyright Notice at the end of this file
*/
 

2.guard define
整個頭文件應該在guard define之間

#ifndef lua_h
#define lua_h

#endif
 另外，如果這個頭文件可能給c++使用，要加上

#ifdef __cplusplus
extern "C" {
#endif
/*The lines within extern "C" */

 

#ifdef __cplusplus
}
#endif
 
3.儘量不要在頭文件中暴露數據結構

這樣可以用戶降低對你的實現的依賴，也減少了用戶的編譯時間

 

typedef struct lua_State lua_State;
LUA_API lua_State *lua_open (void);
LUA_API void       lua_close (lua_State *L);

 可以看到雖然用戶會一直使用lua_State,但是並不知道lua_State的結構是什麼

從一個使用lua的例子程序可以看出：

 

#include "lua.h"
#include "lauxlib.h"
#include "lualib.h"

 

int main(int argc, char *argv[])
{
    lua_State *L = lua_open();
    const char *buf = "var = 100";
    int var ;
    luaopen_base(L);
    luaopen_io(L);
    lua_dostring(L, buf);
    lua_getglobal(L, "var");
    var = lua_tonumber(L, -1);
    lua_close(L);
    return 0;
}

 

4．函數聲明前加XXX_API已利於拓展

 Lua的例子

#ifndef LUA_API
#define LUA_API              extern
#endif

LUA_API lua_State *lua_open (void);

如果定義了LUA_API就是給LUA內部使用的

如果沒定義LUA_API就是for user 的

寫Window dll程序經常會用到

 

#ifdef DLLTEST_EXPORTS
#define DLLTEST_API __declspec(dllexport)
#else
#define DLLTEST_API __declspec(dllimport)
#endif

 

 

5.宏的定義

儘量使用括號來包住所定義的對象

 

#define LUA_TNONE       (-1)

#define lua_register(L,n,f) /
       (lua_pushstring(L, n), /
        lua_pushcfunction(L, f), /
        lua_settable(L, LUA_GLOBALSINDEX))

 
6.目錄結構

一般應該使用一個單獨的include目錄來包含要發佈的頭文件，但不應該把內部使用的頭文件包含進去。

Lua  的 include目錄只包含了三個頭文件

lauxlib.h , lua.h, lualib.h

非常簡潔

 

轉自 http://www.cppblog.com/sandy/archive/2007/05/15/24151.html