CPSC 333: Module Specifications

Location: [CPSC 333] [Listing by Topic] [Listing by Date] [Previous Topic] [Next Topic] Module Specifications

This material was briefly mentioned during the lecture of March 12, 1997.

• Components
• Avoiding an Algorithm
• Data Dictionary

In order to complete the specification of a preliminary (or ``architectural'') design using structured design, you must produce a module specification for each of the modules shown on your structure chart, and make any changes to the systems data dictionary that are appropriate.

Components

At this point, a module specification for a module (``Module A'') should include the following components.

1. The name of the module being specified. This should be the same as the name for the module that's listed on the structure chart (on the rectangle that represents it).

2. A cross reference back to the data flow diagrams - the name(s) and number(s) of the data flow diagram's process (or processes) this corresponds to, if this module was added during a second level factoring step of structured design.

   On the other hand, if the module was added during first level factoring, and isn't a transaction center, then it is one of the ``controller'' modules added during first level factoring, and there wouldn't be a corresponding process in the data flow diagrams - so there wouldn't be anything for you to list here.

3. A list of (the names of) all the modules that can call Module A.

4. A list of all modules that Module A can call.

5. The module's calling sequence: A list of all arguments and values returned, and their types. If you know that C or C++ will be the programming language used, then you should give the function's prototype here.

6. A description of what the module does - or, more precisely, the relationship that should hold between the module's inputs and outputs.

At this point - during preliminary (or ``architectural'') design, it isn't necessary for this last component to be given as an algorithm. Instead, it can include a short comment that describes what the function should do, and a description of the desired relationship between inputs and outputs.

Avoiding an Algorithm

For an example of how to avoid giving an algorithm to solve the problem while giving the above information, consider a ``propositional formula satisfiability'' module,

• whose input consists of a propositional (or ``boolean'') formula, made up of variables x₁, x₂, ..., x_n, that are connected using the logical connectives and, or, and not, and

• whose output will be a truth assignment - an assignment of either true or false as the value for each of the variables x₁, x₂, ..., x_n. Put another way, the output is a sequence v₁, v₂, ..., v_n, where v_i is either true or false for all i, and where v_i is understood to be the value ``assigned to'' the variable x_i in the truth assignment that is being returned.

Recall that a boolean formula is satisfiable if some truth assignment gives the formula the value true), and that the boolean formula is unsatisfiable otherwise.

If the module is supposed to ``find a satisfying truth assignment, if one exists,'' then the ``description of what the module does'' might consist of the following rule.

If the input consists of a well formed boolean formula, and that formula is satisfiable, then the truth assignment given as output is a satisfying truth assignment for it (that is, the output truth assignment assigns the value true to the input formula).

If the input consists of a well formed boolean formula that is unsatisfiable, then the output should be some (any) truth assignment for it.

Finally, if the input isn't a well formed boolean formula at all, then the output should consist of a status message that identifies this problem.

This says how the output should be related to the input, but it doesn't given an algorithm that can be used to find the output. (See CPSC 413, next year, for evidence that you shouldn't expect to find an efficient algorithm for this problem, and for an explanation of why this fact might be important.)

More generally, the module specification should include the following at this (early) point during design, as the sixth component listed above:

• a specification of necessary relationships between inputs and outputs under normal conditions (this can but doesn't need to include an algorithm);
• any error conditions that the module should be expected to check for and report, and the required relationships between inputs and outputs when each of the error conditions is detected;
• any assumptions that can be made - conditions that will be assumed to hold when the above requirements must be satisfied. In general we ``don't care'' what the module does when these assumptions aren't satisfied (so, ``any output at all'' is acceptable in this case). These assumptions are not generally things that the module's ``production code'' (the code that is executed in the delivered system) should explicitly test for. However, the module might include additional ``testing" code,'' that is executed by pre-release versions of the module (during system testing), which does check these conditions.
• if an ``error code'' is returned as the function value or as one of the function's outputs, then each of the possible values of this error code should be given, and their meanings stated.`

Note that this isn't very different from the information required in a process specification that's developed at the end of structured analysis.

Later on, during detailed design the algorithm that will be used to implement the module will be selected, and ``part 6'' of the module specification will be expanded to include pseudocode for this algorithm (and, possibly, a reference to a description of this algorithm, if it's described in a textbook, journal, or some other standard place).

Data Dictionary

The system's data dictionary should be revised to include any definitions of data and control signals shown on the structure chart if these haven't been defined already. In most cases, these will correspond to data or control flows on the system's data flow diagrams, so there won't be much to do.

Location: [CPSC 333] [Listing by Topic] [Listing by Date] [Previous Topic] [Next Topic] Module Specifications