摘要:本文主要討論如何書寫權(quán)威的庫頭文件-c or cplusplus.
如何書寫權(quán)威的頭文件?
這是個問題
如果看得代碼多了,經(jīng)驗多了是不是可以得出權(quán)威的頭文件應(yīng)該滿足這個樣子?
1.必要的版權(quán)格式或者文檔說明
2.作者,日期,地點,版本等信息
3.如果有必要盡可能不要使用中文,這些寫出來的文件看上去很牛逼
4.關(guān)于注釋:使用統(tǒng)一的注釋風(fēng)格 這樣弄出來的文件看上去很有美感
5.盡可能使用統(tǒng)一的文件編輯器，免得影響在其他編輯器出來的效果
6.使用宏防止重復(fù)包含頭文件
比如 #ifndef ..
7.考慮庫是不是平臺相關(guān)的
如果必要加上判斷平臺的宏 這樣讀者會感覺專業(yè)很多
8.如果必要重新定義基本類型
比如typedef unsigned int uint.----為了打造權(quán)威 我們一定要這樣做
9.為了進一步鞏固我們的權(quán)威形象-我們可以根據(jù)平臺加入需要的頭文件
比如:
#if defined(__FreeBSD__) && (__FreeBSD__ >= 2)
/* Needed for __FreeBSD_version symbol definition */
#else
#endif
10.盡可能的多使用宏
比如一般情況下TRUE都是定義過的
為了體現(xiàn)庫的權(quán)威性 我們這樣弄
#ifndef TRUE
#define TRUE 1
#endif
11.如果是c接口的庫
頭文件還需要加上
#ifdef __cplusplus
extern "C" {
#endif
12.對于命名格式 在保持統(tǒng)一的情況下我們最好不采用一般的命名格式
不要使用通用的setValue也不采用SetValue或者set_value
那如何寫呢？
可以這樣
XX_setValue 在這里XX代表庫的縮寫
比如Python 就是Py
專家就是要和別人不一樣
13.如果是cplusplus庫接口，那么庫的頭文件中盡可能的使用抽象基類，甚至使用虛析構(gòu)函數(shù)。
如果需要或者對象指針我們可以增加一個接口比如GetObject
14.頭文件盡可能的不要包含不相關(guān)的內(nèi)容-原則讓用戶知道她想知道的隱藏她不需要的
15.對于句柄類的我們一定要使用pimpl技法
比如lua中的lua_State句柄就是
typedef struct lua_State lua_State;
16.如果需要命名空間，一般情況下我們會這樣比如:
namespace core
{
..
}
考慮到第10個原則這樣弄吧
還是使用宏
#define BEGIN_CORE_NAMESPACE namespace {
#define END_CORE_NAMGESPACE }
比如QT中就是這樣弄得
BEGIN_QT_NAMESPACE
class QLabel;
class QSpinBox;
class QSlider;
class QAction;
END_QT_NAMESPACE
freetype中類似的是FT_BEGIN_HEADER
17.如果需要導(dǎo)出鏈接
如果這樣寫只能說明你是初級水準(zhǔn)
GAPI void G_CALL gTerminate();
那如何寫你？
做法就是再定義一個后
比如
#define G_EXPORT(para) GAPI para G_CALL
然后這樣使用
G_EXPORT(void) gTerminate();
如果這樣弄不想權(quán)威也不行
18.總結(jié):
權(quán)威就是要讓別人不能置否，要讓讀者知道這樣就是對的。
PS：如果堅持這樣，過不了多久，你肯定就是權(quán)威
附注：雖然一切都是神馬