FAQs

(Frequently Asked Questions)

TSRI System-Level Design HTML Documentation

Frequently Asked Customer Question: Can you describe the system-level design documentation that TSRI generates as part of its automated system modernization services?

TSRI Answer: If requested, TSRI generates a high-fidelity, richly-indexed hyperlinked system-level detailed design document encompassing the customer’s entire system at the beginning of a project when the system is in its legacy or “As Is” state and at the end of our services when the system is in its modernized or “To Be” state. This documentation is delivered in an easily navigable web-based form. The principal design artifacts generated by TSRI’s automated documentation process are defined below.

Documentation Products: The following products are generated for every functional unit of code and fully integrated in TSRI’s documentation deliverable, with hyperlinks provided between corresponding source and target (legacy and modernized) system application code, such that the line of the code is repositioned to the top of the display window as each node in the diagram, table, model or graph is selected:

Control Flow Graph
Structure Chart
Data Element Table
State Machine Model
State Transition Table
Cause Effect Graph
State Machine Model
‘As Is’ Model
‘To Be’ Model

Product Definitions:

1. Control Flow Graph (CFG): A graph of the control relationships between conditions, program branches and called procedures in an application’s paragraph or program. The CFG is depicted as a scalar vector graphic (SVG) graphic.

2. Structure Chart (SC): A graph of the call relationships between paragraphs or programs and optionally, the data inputs and outputs associated with the procedure call.

3. Data Element Table (DET): A tabular description of the location and usage of the definitions and references to data elements that occur in an application’s paragraph or program. DETs are used as the basis for data analysis and the definitions of relationships between procedures and data definitions

4. State Machine Model (SMM): A graph of the states and state transitions of a procedure in which states are depicted as bubbles and state transitions are depicted as arcs between the states. The set of individual conditions in the preconditions associated with the set of state transitions out of a state are considered the control variables of the state. There is one action sequence associated with each state transition and one Boolean value assignment to the preconditions associated with each state transition. There is one or more state transitions (arcs out) potentially associated with each state and potentially zero or more state transitions coming into each state. There is a begin state and one (or more) end states associated with each state machine. A state machine is isomorphic with a state transition table.

5. Cause/Effect Graph (CEG): A graph that depicts a sequence of rules that govern program behavior in terms of cause and effect nodes in a directed fashion. A cause in a CCEG graph is an assertion of a Boolean value assignment to an observable condition or an assertion that an observable behavior (effect) has occurred. A CEG for a procedure or a program is a connected graph of cause and effect nodes for the procedure or program as a whole that operationally define a sequence of rules (precondition and associated action) that define the behavior of the program. A CEG is isomorphic with a state transition table.

6. Data Flow Graph (DFG): A graph of the flow of data and of the transformations applied to data between the data stores of a program. Data stores (such as data records or classes) are the data structures used by the program for the storage of program data. Data flows are the fields or attributes used or assigned values by the data transforming statements of the program. The transformations are contiguous sequences of program statements that sequentially process input data to produce output data. The data transformations that update a data store as a whole or a substructure of a data store are called Methods. A paragraph data flow model is a formal description of the flows of data between data stores referenced within a paragraph. Nodes in a paragraph data flow model consists of data stores and data transformation processes. A data transformation process node can encapsulate several program statements that read and update several data stores.

7. State Transition Table (STT): A table that provides a formal description of the state transitions of a state. A state table can be constructed for a state, a state transition, or an entire paragraph. An STT consists of a three part table consisting of: (1) preconditions and their Boolean value assignments; (2) the set of state transitions achieved by satisfying preconditions; and (3) the set of actions taken upon satisfaction of the transition preconditions. A STT is a formal description of the control conditions, actions, and state transitions of a particular procedure or of a state within a procedure. A state transition consists of a Boolean value assignment to the control conditions of the state (the precondition) and the sequence of actions (expressed as methods or block level program slices) taken in the event the preconditions of the transition are satisfied. An STT for a procedure is isomorphic with a cause/effect graph and a state machine model.

8. ‘As Is’ Documentation: ‘As Is’ documentation is a functional analysis level design model of the legacy system application code in its original state, prior to modernization.

9. ‘To Be Documentation: ‘To Be’ documentation is a functional analysis level design model of the legacy system application code in its original state, after modernization. The documentation provides a hyperlink between the legacy ‘As Is’ source code and the modern target code, maintaining line level correspondence between each line and every data element.

TSRI Modernized Code Quality & Maintainability

Frequently Asked Customer Question: I am concerned as to the quality and maintainability of transformed code automatically generated by TSRI. Since I have the dual goals of platform migration and improved application agility, the ability for my staff or a selected support integrator to maintain and enhance the transformed application is an important factor in choosing the optimum migration strategy for my project. How does TSRI respond to these dual needs?

TSRI Answer: In our experience, code quality and maintainability are notoriously subjective concepts. However, if you are willing to establish objective metrics (rather than purely subjective ones) for code quality and maintainability our approach can be shown to meet your code maintainability and quality requirements using automated and semi-automated transformation rather than human labor to bring about the code enhancements according to those metrics. For example, one of our customers adheres to a European standard for code maintainability that is based upon two primary criteria: Essential Complexity and the Number of Comments in the code. By those criteria any transformation TSRI performs (even without re-factoring) would improve or keep code quality the same given that we preserve comments and we reduce code complexity during our automated transformation process. If additional criteria for quality and maintainability are used, such as code redundancy, code similarity, dead code, adherence to naming standards, code componentization, etc., we have automatic (no human in the loop) and semi-automatic (human directed) re-factoring operations that change the code to bring about quality and maintainability enhancement as measured by these objective metrics. Obviously this is a partial list. In our soon-to-be released JANUS Studio^TM we typically apply 18 standard automated and semi-automated re-factoring operations whose only purpose is to increase quality and maintainability, with that standard list just being a starting point. We can apply many other kinds of custom re-factoring operations, depending upon our customer’s needs.

Other objective factors to be considered in the quality and maintainability equation are time, risk, cost, reliability, repeatability and perfectibility of the process that is used. By all of these measures our highly automated and traceable approach to achieving higher quality and higher maintainability through the use of objective criteria is superior to any ad hoc approach associated with purely manual approaches.

If we wish to resort to subjective criteria, such as human testimonials, our customers for systems such as the 13 radar systems in the Ballistic Missile Early Warning System, which are being rebuilt around our transformation of Cobra Dane from Ada to RT Java; our transformation of the Patriot Missile command and control system from Ada to C++; our transformation of the European Air Traffic Management System; our transformation of the Milstar military satellite communication system are but a few of many, many examples of mission critical systems for all of which the life cycle maintainability and source code quality were paramount concerns and driving factors on the customer’s source selection of TSRI.

So, whenever we are asked about code quality and maintainability our first response to our customer typically is: Let's agree we won't use any subjective criteria for measuring code quality and maintainability. Let's also agree to establish objective criteria for measuring code quality and maintainability. Let's then match TSRI's transformation and metrics driven re-factoring processes against those criteria adding the supplementary criteria of time, risk, cost, reliability, repeatability and perfectibility to establish the appropriate economic equations. With that criteria established, we will then compare and measure code quality and maintainability using economic equations that objectively define these properties.

Such objective maintainability and quality measurements are:

Cost for enhancement per unit
Time for enhancement per unit
Risk for enhancement per unit (error introduction and what is the cost per error)
Reliability: Uniform enhancements for unit(1) to unit(n) (i.e., how many missed or misapplied enhancements were there)
Repeatability: Same enhancements uniformly applicable to unit(k+1) to unit (n)
Perfectibility: Next enhancement (k+1) applicable to unit (1) to unit (n).

With that done, we will then apply this formula to a suitably chosen alternative. And while not a one-to-one comparison, a good example is TSRI’s transformation and extensive re-factoring of a 600K SLOC acoustic signal processing system for the Navy’s P-3 Orion aircraft versus the efforts of a major integrator to manually transform 12M SLOC of the Air Force’s F-18 mission software. TSRI took 14 person-months to transform the code and re-factor it to a quality ready for testing and future maintainability. The major integrator took 600 person-years to do the same for the F-18.