模块设计与实现经验总结(四)

4  代码编程指南与过程规范

强烈建议采用测试驱动的模式来完成代码编程。测试驱动开发中编写测试代码目的是利用测试代码来描述和确认类的功能规格，然后编写实现代码来实现测试代码规定的功能规格并利用测试来验证编写的代码确实是符合事先设计好的功能规格。

根据前面的阐述，在详细设计时是不可能把每个类设计的很细，也就是每个类很细致的功能规格是没有设计好的。此部分工作是留在代码编写阶段来完成的，即在代码编写阶段包括：类功能规格设计和实现。

大部分开发者在编码时其实是在一边在编码实现、一边在确定类和方法的功能规格，并且会不断的调整(有时候会因为突然想到一种以前没考虑到的情况没处理、有时候是为了代码实现简单等等)。此时由于大部分精力是在考虑实现，并且是局部的实现，很容易导致某些需要全局考虑的一些例外或者异常情况没有考虑到，从而出现BUG。通过测试驱动模式可以强制大家把第二部分所讲的两个阶段区分开。

4.1代码编写建议采取以下步骤

ü 写代码前，先站在使用者角度考虑清楚将要实现的类功能规格。类分为高层类和低层类(例如数据库连接池代码，数据库连接池类属于高层类、数据库连接类属于低层类)。一般情况下会出现一个高层类和多个低层类组成一个内聚的包。在这种情况下，可以先写出整个包或者高层类的功能职责,然后逐步下低层的，也可以先写低层再写上层，具体过程看大家自己。因此不管怎么样，都会出现类职责调整的情况发生。

ü 编写类名和类中间的方法，但是不实现。

ü 以注释方式，描述类的职责、本类一些关键或者复杂的策略(方便别人能读懂你的代码)、本类需要处理的情况（要求从设计上，每个类职责要单一，否则这里就会写的很复杂）。

ü 以注释方式，详细描述public方法功能规格，特别是各种异常和例外情况下的处理方式（此时还没有私有方法，类的职责是通过public方法来体现的）。

ü 根据上述注释，以类为单位编写测试代码。

ü 实现各个方法，并通过测试。

 

4.2对于编写测试代码的建议如下

ü 必须先写测试代码

ü 尽可能的去写测试代码

ü 要以类的使用者角度来编写测试代码。

ü 针对类的功能点来写测试代码，而不是针对方法

不要采取为每个Public方法编写一个测试方法的模式来编写测试方法。每个测试方法应该测试的是该类需要处理的某一种情况。因为类的一个功能点可能要涉及多个Public方法。

类似软件测试每个测试用例，都对应一个测试点一样。每个测试方法其实都是测试类的一个功能点。

例如：一个队列类，有pop和push两个public 方法。则不要写两个测试代码：一个是testPop，一个是testPush。

而是要站在使用者角度来考虑队列类的功能规格：

1) 如果队列为空，则弹出空对象。

2) 队列应该保证先进后出。

3) 如果队列满，则Push失败。

然后针对以上三种情况，分别对应写出三个测试函数。

5  模块功能说明编写规范

5.1编写模块功能说明的目的

l 编写完整个模块后，从模块整体思考和检查所实现的模块是否符合设计要求，以及在相应细节处理方面是否存在BUG，或者不合理的情况。

l 方便开发人员和维护人员日后的维护

5.2功能说明内容及规范

编写功能说明时，由开发人员站在使用者角度来描述和重新审查模块

1、模块部署环境和与周围模块交互情况描述

u 以图方式描述本模块与周围模块的交互情况，以及部署方式。

u 本模块调用的外部接口描述。

u 本模块对基础环境要求：内存、网络、磁盘等。

2、模块配置说明

u 配置文件设计理由，那些固定不变的，哪些是应对业务变化。

u 仔细描述各个配置文件的含义

u 说明如何通过配置来对应业务变化

3、模块功能说明

详细描述本模块的功能点。对每个功能点，一般描述以下几个方面：

u 功能名

u 与该功能相关的配置文件中的配置项

u 处理流程

u 故障处理

u 可能存在的问题。

例如：

ü 功能N：按比例删除老数据

ü 相关参数

STORE_POLICY :各数据类型的存储比例

PARTITION_MIN_FREESIZE_GB:每个分区应该保留的剩余空间

DELETE_INTERVAL_MINUTE:老数据覆盖的触发间隔。

ü 处理流程

1) 判断是否所有磁盘分区的数据块都被扫描，如果存在退出

2) 判断是否获取了所有磁盘分区的总空间TotalSpace，如果存在某个分区因故障无法获取,则退出。

3) 针对本小组内每种数据类型执行下列步骤  

4) 根据块信息计算出本数据类型所有数据块的总大小UsedSpace

5) UsedSpace < (TotalSpace– 磁盘个数* minFreeSpace)* storagePer则退出类型处理

6) 计算UsedSpace -  (TotalSpace – 磁盘个数* minFreeSpace)* storagePer得到需要删除空间needDelSize。

7) 依次删除登记表中本类型最老数据块，直到删除块总大小大于needDelSize,或者删除干净。

 

ü 故障处理

1. 被删除数据块不存在：删除逻辑直接返回删除成功。

2. 被删除数据块删除失败（远程代理通讯失败、该分区目前不能访问、被占用无法访问等）：将该数据块加入到“删除失败数据块列表”，定期重试。

3. 磁盘分区故障:  导致从来没有成功获取过总空间，会导致所属小组会覆盖停止工作，导致没有成功扫过数据块,会导致所属小组覆盖停止工作。

4. MASTER重起，会导致“删除失败数据块列表”被清空，不过MASTER重起会扫描到所有数据块，并重新删除。

 

ü 可能存在问题

1) 实际数据块分布与MASTER记录不一致，导致错误删除老数据。例如有人手工删除了一块比较新数据。

2) 有些删除失败数据块，会导致实际剩余空间不够。

 

4、模块故障诊断说明

模块故障诊断用于当开发人员不在时，维护人员可以根据此部分初步判断出模块工作不正常时的原因。

由于一般模块出问题，开发人员去维护，一般都是先检查是否是本模块依赖的其他模块或者环境不正常，如果本模块所依赖的环境和模块都正常，那么可能是本模块的问题。诊断说明里要描述所有的检查步骤。可以依次写出所有的检查步骤，每个检查步骤包括：

n 检查方法：如何检查(检查日志中的异常输出、检查基础环境)

n 异常原因：XXX硬件故障、XXX软件故障、XXX模块异常