文件版式

 最近在看林锐博士的《高质量程序设计指南》一书，看到不少感觉有用的东西，在此简要记录一下。

头文件版式

头文件应该包含的内容有：

1. 1. 头文件注释（文件说明、功能描述、版权声明等）--必须有
   2. 内部包含卫哨开始（#ifndef XXX/#define XXX）--必须有
   3. #include其他头文件--如果需要
   4. 外部变量和全局函数声明--如果需要
   5. 常量和宏定义--如果需要
   6. 类型前置声明和定义（class A;）--如果需要
   7. 全局函数原型和内联函数的定义--如果需要
   8. 内部包含卫哨结束（#endif）--必须有
   9. 文件修改记录

其中，头文件注释示例如下：

/************************************************************************
* Copyright(c) 2011-2012 Company Name
* All Right Reserved
* 
* 文件名称: filename.h
* 简要描述: 简述文件内容、功能
* 
* 当前版本: 1.2
* 作者/修改者: 
* 完成日期: 
* 修订说明: 
* 
* 取代版本: 1.0
* 修 改 人: 
* 完成日期: 
* 修订说明: 
************************************************************************/

 源文件版式

源文件应该包含的内容有：

1. 源文件注释（文件说明、功能描述、版权声明等）--必须有
2. 预处理命令--如果需要
3. 常量和宏定义--如果需要
4. 外部变量的声明和全局变量的定义及初始化--如果需要
5. 成员函数和全局函数的定义--如果需要
6. 文件修改记录

函数头需要有函数头注释，如：

/************************************************************************
* 函数名称: 函数名
* 功能描述: 简述函数功能
* 参数列表: Param1---描述
*           Param2---描述
*           Param3---描述
*返回结果: 描述返回值的情况
************************************************************************/

函数注释应当放在函数之前，对于功能简单的函数，可以只用一行注释简单描述其作用或直接不加注释。

 

ADT/UDT版式

ADT/UDT（例如类）的版式主要有2种：

1. private在前，这种通常是“以数据为中心”来设计ADT/UDT，重点关注内部结构；
2. public在前，这种通常是“以行为为中心”来设计ADT/UDT，重点关注其提供的接口（或服务）。

建议采用后一种“以行为为中心”的版式，因为这样可以让自己在设计类时思路清晰，而且方便别人阅读。

以数据为中心的版式： 

class A {
private:
	int i;
	int j;
	...
public:
	void Func1(void);
	void Func2(void);
	...
};

以行为为中心的版式：

class A {
public:
	void Func1(void);
	void Func2(void);
	...
private:
	int i;
	int j;
	...
};