代码目录规范
- 格式：doc
- 大小：101.50 KB
- 文档页数：6
程序模块目录设置
公共程序模块在配置库中首先应该按照trunk、branches、tags进行基本版本管理分支。把程序的主线版本置于trunk下管理，分支版本置于branches下进行管理，把正式发布的版本置于tags下。
在trunk下应设置的目录结构在下表中进行说明。
表格 1 目录结构设置概述
子目录 功能说明
src 存放本模块所有核心代码，不包含对模块部署的理解。（即，这个目录下一般只存放裸代码，不包含所谓的“工程”或“工作区”）。 src目录是无论如何不向其他模块开放的。
为了隔绝src与adapter之间的直接联系，可以在src目录下设置factory目录，存放用于创建adapter对象的工厂类，这样src目录下其他目录就都与adapter没有任何关联了。
test 存放测试代码和测试工程。
component 存放用于部署的组件的工程。存放于该目录的内容应尽可能地“薄”，不应该有核心处理逻辑。是否有component目录存在，取决于该公共模块是提供编译好的二进制组件（exe、dll等），还是直接提供源码。component中组件编译出来的二进制文件存放于bin目录，如果有lib文件和pdb文件则输出到lib目录。
bin 存放二进制组件。和component共同进退。有component，就有bin，没有component就不需要有bin了。
interface 如果本公共模块对外提供接口供其他模块调用，那么应该在interface目录中声明接口。但是要注意的是，仅仅是声明而已。
在interface目录下应该有一份模块接口使用说明，这应该是唯一一份不在docs目录中的文档，它是作为模块发布的内容之一的。
lib lib目录用于存放lib文件和pdb文件。component中生成lib文件和pdb文件应该存放于此。
dependency 本公共模块如果会依赖到外部模块接口，那么需要在这个目录中声明，但仅仅是声明而已，不允许是接口实现在这个目录中定义。
mock 为了便于测试，mock中存放对dependency中所定义的接口的模拟实现，也就是mock对象。
adapter adapter目录中存放对dependency中所定义的接口的真实实现。adapter是本模块中唯一与外部模块存在交互的地方。只有adapter模块可以包含外部的头文件或引用外部的lib等。
docs 存放本模块的设计说明。应合理规划并长期维护。杜绝按项目文档形式存放，而应该是最新的现状呈现。只在必要时才说明历史沿革。
下图是目录设置好以后的简单示意图：
图 1 目录设置示意图
在第一层共计10个目录，不应在这个层次任意增加目录或修改目录名。 2. 各目录间的关系说明
2.1. src、interface、dependency和adapter之间的关系
四个主要目录之间的关系如图所示，src是对interface的实现，src调用了dependency，而adapter则是对dependency的实现；最终与外界交互的是adapter，调用了其他模块的interface。
图 2 四个主要目录之间逻辑关系
四个主要目录之间包含关系如下图所示，从图中可以看出一些规律。
图 3 四个主要目录间的包含关系
其中interface是最整洁的部分，只被其他目录下的代码include，而不会去include别的代码。同时interface也是最不应该随意改动的地方。
适配器adapter是整个模块最“脏”的地方，也是唯一无法避免“脏”的地方。正是由于adapter的“脏”，才可以尽可能使其他部分保持整洁。
Adapter同时是外部其他模块接口改动对本模块发生影响的缓冲地带。
Src对adapter的调用是通过dependency完成的，adapter不应该与src主体有任何直接的瓜葛。但是由于src中的工厂类需要直接创建adapter对象，因此factory无法避免需要了解adapter。可以考虑在src中单设factory目录。 2.2. mock、adapter与dependency之间的关系
设计一个模块之前，首先需要知道哪些提供功能是由外部其他模块提供的，也就是确定本模块的系统边界。把责个系统边界定义在dependency目录中，以此来清晰地表达出本模块对其他模块的依赖关系。
Adapter则负责将外界的功能接口“适配”到本模块所依赖的接口形式。
由于adapter并非本模块的核心逻辑。因而为了便于单元测试，我们设计了mock目录作为对dependency的一种虚拟实现。
图 4 mock、adpater与dependency的关系
2.3. 内部和外部之分
除docs以外的其余目录，有内部和外部之分。所谓外部目录，就是当这个模块发布给某条产品线使用时需要输出的部分；内部目录则反之，不需要输出。
其中lib、bin、interface作为外部目录；其他所有目录都是内部目录，发布时不需要公布任何内部目录。测试工具如需发布则编译出二进制文件放到bin目录去。 其实比较常见的模块发布目录是lib、bin、include；而在我们的设计里面把include替换成了interface。用include更利于外部使用这个模块时候的理解；但是确使得内部开发过程误把一些并非接口的部分也扔进这个目录，增加了不要的耦合。同时我们把接口使用文档也放置在interface目录中，如果目录名字是include就显得名实不符了。
那为什么不把接口使用文档放到docs目录下呢？因为docs目录可能含有很多内部设计的文档资料，如果把要对外发布的文档也放进来，可能会增加发布过程的复杂性。
