首页 > 代码库 > 从文档规范性中想到的
从文档规范性中想到的
软件开发人员不只是要写程序，还要编写各式各样的文档。有的时候，花在写文档上的时间甚至还比花在写程序上的时间还要多一些。很多开发人员认为文档编写不重要，于是敷衍了事，让之后阅读文档的人看得是云里雾里，极大地影响了工作的效率。
最近，我看了两个不同软件版本中的集成测试文档，颇有感触。
集成测试文档1的结构是这样的：
1. 引言
2. 术语、定义和缩略语
3. 集成目标
4. 集成任务
4.1 集成任务1
……
表1
……
图1
……
4.2 集成任务2
……
表2
……
图2
……
4.3 集成任务3
……
表3
……
图3
……
……
5. 集成工具及环境说明
6. 附件
7. 参考文献
集成测试文档2的结构是这样的：
1. 引言
2. 术语、定义和缩略语
3. 集成目标
4. 集成任务
4.1 集成任务1
……
表4.1.1
……
图4.1.1
……
4.2 集成任务2
……
表4.2.1
……
图4.2.1
……
4.3 集成任务3
……
表4.3.1
……
图4.3.1
……
……
5. 集成工具及环境说明
6. 附件
7. 参考文献
大家可能已经看出来了，这两份文档只是在红色字体部分有区别，其它部分都是一样的。在集成测试文档1中，图表的编号采用了“图1、图2、图3、表1、表2、表3”的形式；在集成测试文档2中，图表的编号采用了“图4.1.1、图4.2.1、图4.3.1、表4.1.1、表4.2.1、表4.3.1”的形式。大家也许觉得这个差别没什么，就是一个编号的方案不同而已。
确实，从表面上看只是编号方案不同，但在软件版本不停演进的过程中，差别就体现出来了。为什么呢？请容我慢慢道来。
这两个软件的功能在不停地升级，需要从最开始的1.0版本发展到10.0乃至20.0。每次有版本的升级，都需要在集成测试文档里面补充相关功能集成测试的内容，这主要是在“4. 集成任务”这一节中完成的。也就是说，第4节的内容在不断地添加，也许会从“4.1”发展到“4.20”乃至“4.100”，并且这些添加可能是由不同的开发人员完成的。
当第4节的内容足够多时，两份文档表现出来下面的不同：
(1)对于集成测试文档1，在开始几个版本，图表的编号还正常，按照“图1、图2、图3、表1、表2、表3”的顺序在发展。在经过多次版本的升级之后，问题就出来了。某一个版本的开发人员可能是因为工作忙或者是疏忽了的缘故，将图表的编号搞错了，例如，本来应该是图4和表4，他写成了图5和表5，后面版本的图表编号也就跟着错了。在发展到较高版本之后，图表的编号可能是这样的：“图1、图2、图3、图3、图4、图5、图6、图6、图6、图7……表1、表2、表3、表3、表4、表5、表6、表7、表7、表7……”。很明显，这是很不规范的，影响了对文档的阅读。
(2)对于集成测试文档2，即使发展到很高的版本，也不会有问题，如“4.10”节，图表的编号就是：“图4.10.1、图4.10.2、图4.10.3…表4.10.1、表4.10.2、表4.10.3…”。因为图表的编号只与所在的节有关，不需要与前后节有任何关联，所以能够保证其正确性。
图表的编号虽然是一个很小的问题，但我们却可以从中看出软件的不同设计方案所带来的不同结果。具体而言，我个人认为：
(1)软件产品的设计方案一定要考虑到未来的发展，即可扩展性，要为以后的版本打下一个好的基础。集成测试文档2在这方面就做得比较好，而集成测试文档1没有考虑到未来在编号上出错的可能，这种方案就设计得不合理。
(2)软件产品的设计一定要遵循“高内聚、低耦合”的设计理念，即要减少一个模块与其它模块在数据、消息等上面的关联，而应该增强模块内部的关联性。集成测试文档1中某节图表的编号与前面节图表的编号的关联性很强，而集成测试文档2各节图表编号没有任何关联。因此，在图表编号上的设计，集成测试文档1比集成测试文档2逊色很多。
(3)软件产品的设计一定要体现出专业性。在这点上，“图1、图2、图3、表1、表2、表3”肯定没有“图4.1.1、图4.2.1、图4.3.1、表4.1.1、表4.2.1、表4.3.1”看起来专业。因此，从专业性的角度看，集成测试文档1也要比集成测试文档2差。
编写出专业、美观、整洁的文档是对一个开发工程师的基本要求，同时这也是工程师做事态度、专业素质和能力的体现。一个合格的开发工程师应该是“代码”和“文档”两手抓，两手都要硬。
(本人微博：http://weibo.com/zhouzxi?topnav=1&wvr=5，微信号：245924426，欢迎关注！)