9.4 Software Module Requirements Specification

The module requirements specification is the low-level design specification for the system. At this level, we will be concerned for the first time with implementing the system in a programming language metaphor. Each programming language creates a different metaphor. There is, for example, a C++ machine. This particular language metaphor is created through a very large library of runtime support services. There is a distinctly different metaphor created by the Java runtime environment. We will not concern ourselves with this low-level implementation detail until we actually begin to map our high-level design metaphor onto a particular language runtime environment. The module requirements specification is simply a low-level partition of the system functionality. The three central issues that emerge from the module description will be (1) the structure of the system, (2) the precise specification of data structures, and (3) the data flow from one module to another. There must be, however, a one-to-one mapping between module specifications and code modules. Each module specification will result in exactly one code module. There will be no code modules that do not have design module specifications.

One thing that will become central to our thinking in the module specification is that there must be a well-defined grammar that controls this specification. Our first automatic system measurements will occur at this level. Essentially all of the control flow metrics can be obtained from the design module specifications. All of the pertinent data structures information can be obtained here as well.

It is our expectation that there will be no comment statements in the source code for the program we have specified. All program documentation will be kept outside the source code module. Each source code module will have its own design documentation. All of the pertinent information about the module will be held in the design documentation. If there is a fault in the design, then the design must be modified followed by the associated code modules. The only circumstance under which a code module should ever be modified without modification of its design specification is in the case where the code module does not accurately reflect the design module.

9.4.1 Module Specifications

In our evolving specification scheme there will be a separate specification for each program module. The structure of this specification is outlined in Exhibit 4. In the interest of brevity we will not attempt to build module descriptions for the hypothetical calc system. The most important thing to be established at this point is that there are certain elements of module description that must be specified very precisely at this point.

Exhibit 4: Elements of Module Specification

 Module_Header_Section       <Module Name> with                                <Parameters> In/Out                                <Parameters> In                                <Parameters> Out Call_Section                Called Modules  <Module Name List>|<Empty>                             Calling Modules <Module Name List>|<Empty> Description_Section         Comprehensive description of the functionality                              of the module including:                                Start state                                End state                                Data transformations                                Brief description of the relationship with                              this module to called and calling modules Algorithm_Section           Pseudo-code description of the algorithm for                              this module Data_Definition_Section     Variables:                                Parameter List                                   Incoming                                      <Variable Names>                                   Outgoing                                      <Variable Names>                                Local                                   <Variable Names>                                Constants                                   <Constant List>                             Variable Declarations                                Variable Name :: = <Type>; <Scale>;                                   <Precision>; <Range>;                                   <Parameter>|<Local>

The Module Header Section will articulate the data binding between this module and those that will call it. The Call Section of our module specification shows the control flow binding between this module and those it will call and will be called by it. We will use this section to derive our Fan-In and Fan-Out metrics. The Algorithm Section will be used to derive the module control flow metrics discussed in Chapter 5. The Data Definition Section will show us the scope of each variable. In addition, this section will allow us to specify the precise nature of each data variable and the range of data that it may contain.

9.4.2 Module Call Graph Structure

Once we have built the module specification for each module we can clearly model the interaction of each module with its immediate neighbors. We will know exactly which module calls another module and those modules that call it. The existence of this call graph structure will serve to eliminate one of the most trying software maintenance problems. That is, when the functionality of a module is changed, then any module that invokes the change module will be impacted by the change. The module call graph structure is a graphical image of the system showing the call-return binding of the program modules. Each module, represented by a node in the graph, will be connected to each called module by an arc in the graph. From this graph, the relationship among calling modules can be easily observed.