Cpper
C/C++高级工程师 Android高级软件工程师 IT集成工程师 音频工程师 熟悉c,c++,java,c#,py,js,asp等多种语言 程序猿
摘要:本文主要讨论如何书写权威的库头文件-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:如果坚持这样,过不了多久,你肯定就是权威
附注:虽然一切都是神马



posted on 2011-03-17 16:39 ccsdu2009 阅读(2216) 评论(11)  编辑 收藏 引用 所属分类: 软件工程
Comments
  • # re: 如何书写权威的程序库头文件
    Kevin Lynx
    Posted @ 2011-03-17 18:11
    - -| 别人那样写是有原因的。尤其是跨平台代码(导致各种宏)、开源代码(导致各种版权注释)、避免名字冲突的库代码(导致符号前缀)。。。  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    ccsdu2009
    Posted @ 2011-03-17 18:26
    @Kevin Lynx
    我这样写也有原因 呵呵  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    linux23
    Posted @ 2011-03-18 00:17
    只能说明你还处于一个很肤浅的总是沾沾自喜秀代码的阶段  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    zuhd
    Posted @ 2011-03-18 09:27
    #define BEGIN_CORE_NAMESPACE namespace {
    #define END_CORE_NAMGESPACE }

    对于这样的宏 我实在是不敢苟同啊 和宏的初衷有点背离不是吗?
    至少阅读代码时我要跟踪下definition 装B成分太多  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    溪流
    Posted @ 2011-03-18 09:29
    哈哈  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    pass by
    Posted @ 2011-03-18 09:52
    如果必要重新定义基本类型
    比如typedef unsigned int uint.----为了打造权威 我们一定要这样做

    自己的代码,实在是不想搞这么复杂,我说真的  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    ccsdu2009
    Posted @ 2011-03-18 11:10
    @linux23
    呵呵  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    zwp
    Posted @ 2011-03-18 12:39
    一半搞笑,一半有用。  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    空明流转
    Posted @ 2011-03-18 14:22
    @zuhd
    这个是为了避免namespace在大多数IDE的自动格式化中导致缩进。  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    cpp伪专家
    Posted @ 2011-03-18 14:22
    不知道楼主是真肤浅还是说反话。  回复  更多评论   
  • # re: 如何书写权威的程序库头文件
    ccsdu2009
    Posted @ 2011-03-18 18:33
    @zwp
    如何觉得搞笑 你可以看看很多c++库都是如何写的  回复  更多评论   

只有注册用户登录后才能发表评论。
【推荐】超50万行VC++源码: 大型组态工控、电力仿真CAD与GIS源码库
网站导航: 博客园   IT新闻   BlogJava   知识库   博问   管理