- 2.5.12 Design Techniques and Deliverables
- 18.104.22.168 Introduction
- 22.214.171.124 References
- 126.96.36.199 General Guidelines
- 188.8.131.52 Structure Chart Development and Design
- 184.108.40.206.1 General Development of Structure Charts
- 220.127.116.11.2 Design Strategies and Objectives
- 18.104.22.168 Structure Chart Conventions and Standards
- 22.214.171.124.1 Module Numbering
- 126.96.36.199.2 Module Notations
- 188.8.131.52.2.1 Special Module Call Notation
- 184.108.40.206.2.2 Lexical Inclusion
- 220.127.116.11.2.3 Pre-Existing Module Notation
- 18.104.22.168.2.4 File Notation
- 22.214.171.124.3 Common Environment
- 126.96.36.199.4 Interface Parameters (Couples)
- 188.8.131.52.5 Sorts
- 184.108.40.206.6 Analysis/Design Cross-Reference List
- 220.127.116.11 Module Specification
- 18.104.22.168.1 Pseudocode
- 22.214.171.124.2 Module Specification Development/Standards
- 126.96.36.199.3 Pseudocode-Conventions/Standards
- 188.8.131.52 Packaging and Preprogramming Considerations
- 184.108.40.206 Structured Design/Programming Interface
- Exhibit 2.5.12-1 Example of a Structure Chart
- Exhibit 2.5.12-2 Example of Page 1 of a Structure Chart using a Parameter Table
- Exhibit 2.5.12-3 Contents and Format of Analysis/Design Cross-Reference List
Part 2. Information Technology
Chapter 5. Systems Development
Section 12. Design Techniques and Deliverables
Structured design is a technique that involves the description, specification, and hierarchical arrangement of software components designed to be small, easily managed, independent modules conceived in terms of their inputs and outputs.
Structure charts and module specifications are the tools used in structured design. The deliverables that result from applying structured design are structure charts and module specifications. These deliverables are required to document the design of a system. The resulting overall design is a top-down hierarchy of single entry, single-exit modules designed so that changes can be made with minimal difficulty.
This manual establishes standards, guidelines, and other controls for designing software. This manual describes techniques for structuring a program and specifying the modules that constitute the program structure. This manual is distributed to promote the development of software systems that are easy to understand, change, and maintain.
The guidelines, standards, techniques, and other controls established in this manual apply to all software developed for the Internal Revenue Service. This development includes that performed by government employees as well as contractors. For system development purposes, the controls established in this manual may be used with any Agency approved life cycle (e.g. SDLC, eSDLC, or ELC).
The techniques expressed in this manual are based on concepts expressed by Meilir Page-Jones, in his publication entitled, "The Practical Guide to Structure Systems Design." The International Standard Book Number (ISBN) for this publication is 0-13-690769-5.
Where applicable, naming standards shall be applied. Names, numbers, and all other identifiers shall be consistent among deliverables.
When preparing identifying information for a deliverable, every page must provide standard identifying information. Where applicable, provide the following types of information:
Related Functional Specification Package (FSP) number
Responsible organization (e.g., organizational symbols)
The primary documentation tool of structured design is the structure chart. Each structure chart forms a graphic model of the program's design shown through a hierarchy of modules. Use the structured design technique after structured analysis. One aspect of structured analysis is " packaging" , or subdividing, of the data flow diagrams into subsystems consisting of related groups of processes. In structure design, a separate structure chart will then model each run/process. Although structured analysis provides a bridge to structured design, it is not a prerequisite to the design. Regardless of the analysis technique used, a system still must be subdivided into a group of runs or processes, at which point structured design be begin.
A structure chart is a non-procedural representation of a run/process that depicts the hierarchical organization of this process; the function of each module on the chart is emphasized, rather than the module's logic.
In a project where structured analysis was not required or employed, the principles applied in partitioning the data flow diagrams must still be applied to arrive at a high-level system schematic that then can be used for a design implementation.
Each structure chart shall depict the following:
modules, graphically represented by boxes, joined together in a tree-like structure by
module connectors, graphically represented by lines to show superior and subordinate modules; and
interface parameters or couples, graphically represented by short arrows with a circular tail, used to show movement of data items from one module to another.
The figure below illustrates the basic format of a structure chart. Module names and numbers, and interface parameter names have been omitted for the sake of simplicity, although they normally a part of any structure chart.
Examine the partitioned data flow diagrams and apply transform and/or transaction analysis to accomplish the initial development of a structure chart. Use these strategies to examine and analyze the data flow as graphically presented in data flow diagrams. These strategies require judgment. Apply the basic concepts of transform and/or transaction analysis to any design regardless of whether structured analysis preceded structured design.
Other criteria exist to evaluate and improve the quality of a design. Properly apply the concepts of cohesion, coupling, decision splitting and other heuristics to produce a well-partitioned and easily maintained system.
Use Transform Analysis to analyze the data flow diagram, identify the primary processing functions, high-level inputs, and high-level outputs, and provide a "first draft" of a structure chart, resulting in a design that bears a simple straightforward relationship to the data flow. The final design will be a refinement of this initial structure, which will reflect alterations based on the concepts of cohesion and coupling.
Apply the following steps to develop structures which are fully, or almost fully factored:
Identify highest-level data and the transform center;
Apply first-level factoring; and
Apply full-system factoring.
To identify the highest-level data and the transform center, study each partition of the data flow diagram to determine what point the input data no longer represents input to the system and at what point data can be perceived as becoming output. Consider the following:
Afferent data is physical input data transformed to logical input as it passes through the data flow diagram. As this incoming data moves through the data flow diagram, it becomes more abstract and highly processed until it reaches a point at which it can no longer be considered input. This is the point of highest-level afferent data.
Efferent data is logical output transformed to physical output as it passes through the data flow diagram. If this data is traced back through the data flow diagram, a point is reached at which the output data stream can no longer be recognized as output. This is the point of highest-level efferent data, the point at which the data elements have had the least amount of processing to convert them to output data.
The data transformation(s) between the afferent and efferent data elements represents the transform center, where data not recognizable as either input or output is processed.
A data flow diagram may contain multiple afferent and efferent streams and/or transform centers.
Figure 2.5.12-2 illustrates a simplified example of a run/process to which transform analysis has been applied.
To apply first-level factoring, identify sub functions subordinate to a module. At the first-level, this results in modules that represent afferent and efferent data streams and the central data transformation point. The following figure illustrates first-level factoring.
To apply full-system factoring, break down each branch of the system into sub functions to the lowest process level and physical input/output module to accomplish full-system factoring. The following figure depicts a structure chart that models an example of a transform-centered system.
Use transaction analysis to analyze the data flow diagrams and develop a module structure that is based on the processing of transactions. A transaction is any element of data, control, signal, event, or change of state, which causes an action.
To apply transaction analysis, perform the following steps:
Identify the sources of transaction.
Identify transactions and the processing that takes place for each transaction.
Specify a module to process each transaction.
Factor each transaction module by developing subordinate action modules.
Factor each action module by developing subordinate detail modules.
The following figure shows a data flow diagram for a transaction-centered system.
Develop the structure chart below for a transaction-centered run/process. See Figure 2.5.12-6. Module 1 is the "Transaction Processor " . Modules 1.2, 1.3, and 1.4 are the "Action Modules " . Module 1.2.1, 1.2.2, and 1.3.2 are the "Detail Modules " .
Throughout the development of the structure chart, determine what information a module needs in order to function. Once a preliminary design is developed, specify the information that is external to that module on the structure chart, in the form of parameters.
Use parameters to pass information from one module to another. Parameters can be data or process control information. Parameter passing allows modules to be independent of each other.
Although information can also be accessed from a common environment, this increases the complexity of the design and binds modules together (increases coupling). Limit your use of this approach. Ensure that the design only reflect the data, which each module needs in order to do its job (e.g., if the program under design evolves into a single unit that can be compiled, do not treat the entire data storage area as common).
Once a structure chart is developed using transform and/or transaction analysis, evaluate it and identify those areas that can be refined. By using the concepts of coupling and cohesion, and applying the rules of thumb described below, the designer can identify and improve the structure of the system.
The revised structure chart must result in an improved design that does not deviate drastically from the original design.
Use the following three methods to identify the strengths and weaknesses of a design:
Cohesion measures the strength of associations between the processing elements within a module. A processing element can be a statement, segment, or sub function.
Maximize the relationships among the elements to obtain an optimal modular design that will increase the reliability, extensibility, and maintainability of the program. Strong and independent modules can often be used in other programs.
A highly cohesive module is a collection of statements and data items that must be treated as a whole because they are functionally related, that is, the module performs a single function.
Acceptable but weaker cohesion exists in a module when several related tasks are grouped together because they are strongly bound by use of the same or closely related data items.
Unacceptable cohesion exists in a module when it performs unrelated tasks, bound together by weak relationships.
Name the module or describe its function in a single sentence to test for strong cohesion. If this can accurately be done using only one transitive verb and a specific non-plural object, then the module is of acceptable cohesion.
Apply cohesion to individual modules as well as the whole design structure. When applying this name test, ensure that the upper level module's name reflects the function of the modules subordinate to it.
Coupling measures the interdependency between modules. A design that has minimal coupling between its modules is easy to maintain. The higher the degree of coupling, the more a programmer will need to consider other modules when coding, debugging, or modifying one module, and the more likely it will be that a change to the inside of one module will affect the proper functioning of another module. Low coupling between modules signifies a well-partitioned system.
Three major factors that can increase or decrease coupling, these factors are:
Type of Connection between Modules
Complexity of Interface
Type of Information Transmitted between Modules
The type of connection between modules involves:
A minimally connected system includes modules with single interfaces supported by parameter passing (one entry/one exit, with return always to the calling module at the next executable instruction). Minimal connectivity is the acceptable standard.
A system that contains modules with multiple entry points, alternate returns, unconditional transfer of control to a normal entry point, or any combination of the three is undesirable and unacceptable.
A system that includes unconditional transfers of control to labels within other modules or explicit references to data elements in other modules introduces invisible coupling. This type of coupling is also unacceptable.
The number of different items/connections passed between modules determines the complexity of an interface. Simple interfaces, which involve the passing of minimal information that is directly accessed, are best.
The types of information transmitted between modules involves:
Data are information, which is operated upon, manipulated or changed by a module, and is essential to the functioning of a module.
Control information is any flag, switch or variable that regulates the flow of processing. Control information causes modules to be interdependent and its use must be minimized.
Use the following rules of thumb to complete the evaluation of a design:
Limit Module Size and Complexity. Use the projected number of statements to determine whether a module is too small and must be combined with others or a module is too large and must be broken down into sub functions. For example, when a module is coded during programming, module size may require 10-100 statements for assembly language and 10-50 statements for a high-level language.
Limit the span of control (fan-out) to 2-9 immediate subordinate modules. The number of subordinates contributes to the complexity of a module's processing. Combine subordinates if the span of control is high. If the span of control is low, compress the subordinate module into the immediate higher, super ordinate module.
Maximize fan-in. Fan-in is the use of a subordinate module by more than one super ordinate module. This avoids duplicate code.
Verify scope of effect and scope of control to insure that modules affected by a decision are subordinate to the module, which makes the decision. Modules, which are higher in the structure, must generally be control modules. These control modules comprise decision logic to control the invocation of their subordinates. Those at the lower level are function modules that perform actual transformations of data such as arithmetic calculations or report printing. Decompose a function into its sub-functions and then continue decomposition until atomic functions are reached. Any module with subordinates must be control oriented instead of performing the actual data transformations.
Make the module name a 2 to 3 word description of the function performed by a module. It must specifically describe what the module accomplishes in respect to its super ordinate. The following figure illustrates this convention.
Organize structure charts in run number sequence
In leveling modules, limit the module levels to five for each page of a structure chart.
Ensure that the number of a module indicates the level of the module in the hierarchy and its related super ordinate module. In the following example, preceding 0's and decimal points have been omitted (i.e., Modules 0.1, 0.2, and 0.3 are numbered 1, 2, and 3 respectively).
Multi-page charts will be necessary for most runs or subsystems. When a run/process is too large to be shown on a single page without crowding, portray the lower-level components of each major processing leg on separate pages. The full set of charts will model the same complete run or subsystem as a single huge chart, but this set will be much easier to update and maintain.
The first page must show at least the main coordinating modules and the high level modules; existence of subordinate modules must be indicated by use of broken lines and page number references. The page number must be shown in the upper right-hand corner of each chart. The following figure provides an example:
Designate a subsequent page for each major processing leg and must be numbered and the continuation annotated as shown in the following examples of pages 2 and 3.
Number the modules that are reusable throughout a run/process or between subsystems (i.e., library modules). When a run/process is large and complex, all subsequent occurrences of a reusable module must also refer back to the first occurrence of the module. Show both numbers on the structure chart, to make it easier to locate the module specifications and the coded module since they are numerically arranged. If connectors are not drawn from the super-ordinate modules to the common modules, then the first occurrence module number is shown in parentheses. The following figure illustrates these practices.
Use the following notations to develop a structure chart:
Special module notation
Pre-existing module notation
Lexical inclusion notation
Special module call notations shall only be used in situations that warrant exception documentation, that is, only when it is necessary to include important procedural information in the design of the system. Since these symbols tend to clutter a structure chart, cause maintenance problems, and are subject to varying interpretations, limit usage to exceptional cases.
Module 1 calls Module 1.1 conditionally, based on the result of a major decision in the following figure.
Module 1 loops through calls to 1.1 and 1.2 in the example below:
This notation indicates the statements that constitute a module are written contiguously, that is, coded in-line, within the boundaries of another module. Module 1.1 in the example below is actually in-line code to Module 1; it is lexically included in Module 1.
Pre-existing Module Notation indicates a module developed or used before (i.e., noted elsewhere in the structure chart). In the example below, Module 1.1 is used elsewhere in the system and striping the module representation shows that fact.
File notation indicates a data file. It can be used when representing an internal sort file; however, its use is generally discouraged.
This information is noted at the bottom of the structure chart. Modules actually using the data are to be identified in parentheses. In the example below RANGE-TABLE is common to modules 1 and 3:
Information flow between modules must consist only of the passing of parameters. A line connecting two modules on a structure chart defines the interface between those modules; the parameters flow along this interface.
The names of data parameters (couples) must match those names used in the FSP whenever possible. The data flow diagram names in the FSP often show modifiers (i.e., NAME-CONTROL-(VALID), NAME-CONTROL-(INVALID)) to represent the logical flow of data. As the structure charts depict the physical flow of data, only the pure data name may be shown, without illustrating any modifiers.
Make the control couples descriptive.
Identify the parameters (couples) by using either the structure chart or a parameter list.
To use the structure chart to identify parameters, use a short arrow with a clear or a solid circular tail indicates each parameter. The arrow indicates the direction of flow along the interface. The following figure illustrates these conventions.
The name or identification of the parameter appears beside the arrow. The following figure depicts a structure chart with labeled parameters.
To use a parameter list:
Number each module connector and create a table listing the module connector numbers and the related input and output parameters. Identify a control parameter by underlining its name in the parameter table.
Sparingly use the parameter list, a labeled parameter arrow along the interface line can be comprehended more quickly than a numerical reference to an entry in a table. To avoid flipping back and forth among the pages of the documentation, the parameter list must appear on the same page as the related portion of the structure chart.
If the number of parameters or the length of the parameter names clutters the structure chart, then a parameter list may be particularly useful. Exhibit 2.5.12- 2 provides an example of page 1 of a structure chart using a parameter list.
A stand-alone system sort or a straightforward internal sort that is shown as a separate run/process on a schematic diagram must not be depicted on a structure chart but must be documented in the run description.
If an internal sort is an integral part of the overall program design, show it on the structure chart in order to present a coherent representation of the process. Show Sort input or output files on a structure chart for the sake of clarity.
In large and complex projects, there may be a need for an audit trail between the modules of a structure chart and the process specifications of a functional specification package. In this case, attach a list cross-referencing each individual module on a structure chart to the corresponding process specifications in the functional specification package that describe the transformation of data parameters entering and exiting that module. See Exhibit 2.5.12- 3.
Include a cross-reference list when:
a project manager determines that it is necessary for project control purposes or that it would significantly enhance the usability of project documentation;
the cross-reference is requested by quality review (i.e., Internal Audit, Quality Assurance, testing personnel).
Module specifications provide the link between structure charts and the coding of structured programs. In effect, the structure chart shows the architecture of a system, not the sequence of procedures, which transform system input to system output. However, in order to proceed with programming, we must know the transform from input to output affected by each module of a structure chart. When a module is invoked, a module specification defines what happens.
There are basically two types of modules that comprise a structure chart: data transformation modules and control modules. Although specification of the internal logic of a module is generally considered a programming task, there is considerable overlap between the design and programming activities at this stage, just as there was between analysis and design when packaging the data flow diagrams. It is therefore necessary to specify procedural detail for both data transformation and control modules.
Pseudocode is an informal language that is similar to structured English, is a type of module specification that describes in code like terms how to do the transform effected by a module. As pseudocode is much closer to actual code than structured English, it allows less margin for misinterpretation and must be written using only the three basic constructs of programming: sequence, selection, and iteration. The specified logic for each module must not be oriented to any specific programming language.
Pseudocode ensures that the logic of every module is structured. Pseudocode, can be shown graphically to help to display the control structure while depicting program logic. Graphic pseudocode is easily maintained, more meaningful, and cannot be used to show "GO TOs" . Its use tests the feasibility of the implementation of a structure chart module and aids in limiting module size.
For control and data transformation modules, pseudocode will be developed for each module on the structure chart. Either a Structured English, Warnier-Orr, or Nassi-Shneiderman format may be used for the pseudocode. This task begins in the design stage and, by the programming stage, must be completed.
Do not write program source code for a module until pseudocode for that module has been completed.
Begin the development of pseudocode (especially for high level modules) during the design stage.
Once the pseudocode for a given module is complete, source coding may begin for that module, (i.e., higher level modules may be source coded before the pseudocode for the lower levels has been developed).
Develop pseudocode for any remaining modules during the programming stage.
Use the same form of pseudocode for all modules in any given system.
The following header information must be present on all pseudocode:
Programmer/Designer - Person responsible for the logic of the module.
Date - The date of origination or revision.
Program - Name of the program that contains this module.
Module Number - The number assigned to the module on the structure chart.
Module Name - Name of the module on the structure chart.
Input Parameters - The parameters passed to this module from its invoking module.
Output Parameters - The parameters passed by this module to its invoking module.
Local Variables - Variables, flags, switches, work areas used only by this module.
Function - Brief statement describing the function of the module. This must not be a detailed description of the module logic or its internal processing.
Only develop pseudocode for reusable (common) modules to be developed for the first occurrence of the module on the structure chart. The pseudocode must contain cross-references to all other occurrences of the module within the process/run.
For modules that are reused by numerous processes/runs, the pseudocode must also provide a cross-reference to the organization responsible for maintaining it.
Organize the pseudocode in run-module sequence number and maintain it in the project library.
Package the pseudocode developed for common modules with other pseudocode for the system or it may be packaged as a separate' document. If maintained as a separate document, it must by easily accessible and readily available to all members of a project team.
Retain the most current pseudocode as part of the project documentation in the project library. Before coding changes are made to an existing module, update or redo the pseudocode to reflect any logic changes that will occur in the module.
At the end of analysis, partition a single set of data flow diagrams into related groups of processes and manual and automated boundaries are established, that is, the data flow diagrams are packaged. This gives the designer a starting point for the development of the structure charts.
Once the structure charts are completed, they must be reevaluated to see if further decomposing and/or packaging is necessary to meet the criteria of the specific hardware/operating system. Estimate the size of each module. Based on memory requirements of a particular structure, as well as other characteristics such as logical execution patterns and overall system efficiency, it may be desirable or necessary to partition a structure chart into smaller units (for compilation and/or execution purposes). Determine if further packaging is necessary. Use the criteria for packaging to determine which modules must be grouped together and which must be isolated. In general the following guidelines must apply:
Include groups of modules that are frequently invoked or executed, close to one another in the same program.
Define groups of modules so that splitting of preferred groupings by program boundaries is minimized without bringing the size of the program above the allowable maximum for the specific hardware system. This grouping will result in the most efficient packaging for the given structure within given memory constraints.
Figure 2.5.12- 21 specifies grouping criteria for packaging.
Grouping Criteria Priority Rules Volume (if known). Include in the same program modules with high volume of access on connecting references (many activities or many items passed). High volume takes precedence over low volume. Iterations. Include in the same program modules connected by iterated references (loops). Inner loops take precedence over outer loops; loops nested within a module take precedence over nesting by subordination. If volume criteria is known, then this criteria takes precedence over iteration. Frequency. Include in the same program modules with high frequency of access on connecting references (frequent transfers of control or data. High frequency takes precedence over lower frequency. If known, volume and/or iteration are preferable. Interval. Include in the same program, as either the super ordinate or subordinate, any module with short interval of time between activation. Short execution time has precedence over long execution time. This is a low priority criterion. Adjacency. Include the same program modules activated adjacent in time, or using the same data. Very low priority rule, used only when other criteria are not available.
Grouping Criteria for Packaging
The following items are isolation criteria for packaging:
Optional Functions - Separate optional function modules into distinct programs.
"One-shot" Functions - Separate modules that are minimally coupled and used only once into distinct programs (e.g., initialization).
Sorts - Separate sort function modules into distinct programs; separate modules applied on input or output sides of a sort into separate programs; the criteria for grouping modules may take priority.
Data - Separate modules into programs where any resulting intermediate files between programs will be of lowest volume and simplest data structure. The criteria for grouping modules may take priority.
When addressing operator messages, divide all operator messages into information messages and console messages. Only display those messages, which require operator intervention or affect the continued operation of a run stream on the console and, if a run control print log is available, then route all other messages to this log. Keep operator messages to a minimum and make sure all of them are documented.
After structure charts are completed and pseudocode writing has begun, begin development of the interface between the design and programming.
The designers and programmers work together at this point to finalize the design of individual modules prior to the start of actual logic diagramming and coding. There are different points of view as to when to begin coding the program modules as noted below:
Achieve maximum cohesion and factoring, and minimum coupling by completing the structure chart and the pseudocode prior to the actual coding of each module. Although the design is considered complete at this point, the most important advantage of this approach is that the design is more easily altered and refined before code is written. Modules can be added to, or removed from, the structure chart as a result of specification changes in the FSP or programming considerations. Such changes must not involve a major redesign of the system.
It may, however, be more expedient to develop source code for the higher levels of the structure chart before pseudocode is developed for the lower levels.
|12||DEBIT-SECTION, MONEY-BALANCE, TRANS-DATA||DEBIT-SECTION, MONEY-BALANCE, LAST-POSTING-DATE|
|13||CREDIT-SECTION, MONEY-BALANCE, TRANS-DATA||CREDIT-SECTION, MONEY-BALANCE, LAST-POSTING-DATE|