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