摘要:本文主要讨论如何书写权威的库头文件-c or cplusplus.
如何书写权威的头文件?
这是个问题
如果看得代码多了,经验多了是不是可以得出权威的头文件应该满足这个样子?
1.必要的版权格式或者文档说明
2.作者,日期,地点,版本等信息
3.如果有必要尽可能不要使用中文,这些写出来的文件看上去很牛逼
4.关于注释:使用统一的注释风格 这样弄出来的文件看上去很有美感
5.尽可能使用统一的文件编辑器，免得影响在其他编辑器出来的效果
6.使用宏防止重复包含头文件
比如 #ifndef ..
7.考虑库是不是平台相关的
如果必要加上判断平台的宏 这样读者会感觉专业很多
8.如果必要重新定义基本类型
比如typedef unsigned int uint.----为了打造权威 我们一定要这样做
9.为了进一步巩固我们的权威形象-我们可以根据平台加入需要的头文件
比如:
#if defined(__FreeBSD__) && (__FreeBSD__ >= 2)
/* Needed for __FreeBSD_version symbol definition */
#else
#endif
10.尽可能的多使用宏
比如一般情况下TRUE都是定义过的
为了体现库的权威性 我们这样弄
#ifndef TRUE
#define TRUE 1
#endif
11.如果是c接口的库
头文件还需要加上
#ifdef __cplusplus
extern "C" {
#endif
12.对于命名格式 在保持统一的情况下我们最好不采用一般的命名格式
不要使用通用的setValue也不采用SetValue或者set_value
那如何写呢？
可以这样
XX_setValue 在这里XX代表库的缩写
比如Python 就是Py
专家就是要和别人不一样
13.如果是cplusplus库接口，那么库的头文件中尽可能的使用抽象基类，甚至使用虚析构函数。
如果需要或者对象指针我们可以增加一个接口比如GetObject
14.头文件尽可能的不要包含不相关的内容-原则让用户知道她想知道的隐藏她不需要的
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.如果需要导出链接
如果这样写只能说明你是初级水准
GAPI void G_CALL gTerminate();
那如何写你？
做法就是再定义一个后
比如
#define G_EXPORT(para) GAPI para G_CALL
然后这样使用
G_EXPORT(void) gTerminate();
如果这样弄不想权威也不行
18.总结:
权威就是要让别人不能置否，要让读者知道这样就是对的。
PS：如果坚持这样，过不了多久，你肯定就是权威
附注：虽然一切都是神马