读书笔记_高质量程序设计指南C++/C语言_10_文件结构和版式

看代码如看散文

10.1 程序文件的目录结构

良好的目录结构可以方便开发和维护。

        工程开发目录结构例：

1. Include(头文件)
2. Source(源文件)
3. Shard(共享文件)
4. Resource(资源文件)
5. Debug(调试版本生成的中间文件)
6. Release(发行版本生成的中间文件)
7. Bin(程序员自己创建的lib文件和dll文件)
8. 其他的临时文件、数据文件、配置文件、DLL等。

10.2 文件的结构

编译预处理时候，#include”.h“将被.h文件中的内容取代。

编译单元：预编译时将每一个包含的头文件递归的展开后形成的源文件。

10.2.1 头文件结构

头文件中的元素较多，其结构应安排如下：

1. 头文件注释（包括文件说明、功能描述、版权声明）（必须）；
2. 内部包含卫哨开始（#ifndef XXXX/#define xxxx） （必须）；
3. #include其他头文件；
4. 外部变量和全局函数声明；
5. 常量和宏定义；
6. 类型前置声明和定义；
7. 全局函数的原型和内联函数的定义；
8. 内部包含卫哨结束：#endef //XXX（必须）；
9. 文件版本及修改说明。

内联函数的定义应放在头文件中，因为内联函数调用语句最终被扩展开来而不是采用函数的调用机制。

10.2.2 版权和版本信息

版权和版本信息的主要内容：

1. 版权信息
2. 文件名称、简要描述、创建日期和作者
3. 当前版本信息和说明
4. 历史版本信息和修订说明

任何源程序都要使用配置管理工具进行管理，所以版本信息不要太详细。

10.2.3 源文件结构

C和C++源文件主要保存函数的实现和类的实现，其结构一般如下：

1. 源文件注释（文件说明、功能描述、版权声明灯）
2. 预处理指令
3. 常量和宏定义
4. 外部变量声明和全局变量的定义和初始化
5. 成员函数和全局函数的定义
6. 文件修改记录

10.3代码的板式

10.3.1 空行的合理使用

1. ADT/UDT定义之间要留空行。ADT内部的各个访问段（public、private等）之间需要留空行；段内内容按相关性分组，建议在各组之间留空行。
2. 函数定义之间留空行。在函数体内，完整的控制结构及单独的语句块之间分别留出空行；逻辑上密切相关的块之间不要加空行；最后一条return语句前要留空行。
3. 注释行和注释块与被他们注释的程序元素之间不要留空行。

10.3.2 代码行及行内空格

1. 一行代码做一件事，定义一个变量货只写一条语句
2. if、elseif、for、do、while等语句各自占用一行；不管语句中有多少句，必须用 { } 括起来
3. 局部变量在定义的同时应当初始化，最好在同一行内初始化。
4. 关键字之后留空格（const、 virtual、 inline、 case）。if、elseif等后面空一格再加“（”。
5. ”，“和”；“后面加空格，如f（x,  y,  z）。

10.3.3 长行拆分

长表达式要在低优先级运算符处拆分为多行。运算符放于新行之首，使用缩进对齐。常见的有二元运算符、输入输出运算符、函数的形参列表等。

10.3.4

建议修饰符*和&紧靠变量名，或使用typedef做一个类型映射。

int  *x,y;

typedef int* PINT;typedef int& RINT;PINT p1,pw;RINT r1=i,r2=j;

10.3.5 注释风格

注释用途：

1. 版本、版权声明
2. 函数接口说明
3. 重要的代码行或段落提示

使用建议：

1. 注释是对代码的“提示”，而不是文档，不能宣兵夺主，不要眼花缭乱。
2. 如果代码很清楚，请不要加注释。
3. 边写代码边注释，修改代码同时需要修改注释，以保证代码和注释的一致性。
4. 删除没有用的注释。注释应当准确、易懂、无二义性。
5. 注释的位置应与被描述代码相邻。可以上方和右方，不能下方。

对于很复杂的函数，建议采用函数头注释

/********************函数名称：*功能描述：*参数列表：*返回结构：*******************/*

对于ADT/UDT建议采用“以行为为中心”的方式来编写类。首先应考虑提供什么样的接口，使设计者思路清晰。并且用户最关心是接口。