如何书写权威的程序库头文件

摘要:本文主要讨论如何书写权威的库头文件-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：如果坚持这样，过不了多久，你肯定就是权威
附注：虽然一切都是神马

 

转自 http://www.cppblog.com/gaimor/archive/2011/03/17/142057.html