Module Interface Documentation - Using The Trace Function Method - - PowerPoint PPT Presentation

Module Interface Documentation - Using The Trace Function Method (TFM)

David Lorge Parnas Marius Dragomiroiu Abstract The Trace Function Method (TFM) for documenting (both describing and specifying) interfaces for information hiding modules and components is

• described. We begin by explaining the motivation for the method. The concepts
• f event, event descriptor, and trace are defined. Basic functions on event

descriptors and traces are introduced. Finally, the method is illustrated on some simple examples.

Middle Road Software

David Parnas, 2010 March 30 15:14

• 1/47! !

! ! ! !

TFM slides Iowa State.pages

Outline Review of basic software documentation principles Modules and how they communicate Events and event descriptors Traces What the document looks like Completeness and consistency Examples

Middle Road Software

David Parnas, 2010 March 30 15:14

• 2/47! !

! ! ! !

TFM slides Iowa State.pages Needed: a way to describe software without Writing code.! 4 Software Reference Documentation! 5 Defining the required content of documents! 6 This Talk is Not about tabular expressions! 7 Document Roles! 8 Obligations of Those who Agree on a Specification! 9 Software Design Issues! 10 Earlier approaches to module interface documentation! 11 What’s wrong with Giving an Equivalent Program! 12 Strengths and Weaknesses of Various Approaches! 13 Readability! 14 Axiomatic vs. functional Aproaches! 15 What’s new in TFM! 16 Communication with Software Modules! 17 Events! 18 Event descriptors! 19 Traces! 20 Trace Function (TFM) Component Interface Documentation! 21 When is a trace-based document complete?! 22 When is a trace-based document consistent?! 23 What is a TFM specification?! 24 What is a TFM description?! 25 When is an implementation of a module correct?! 26 Modules that Create more than one Object! 27 Primitive Functions on Event Descriptors! 28 Primitive Functions on Traces! 29 Useful Function Generators! 30 Date Storage Module: Schematic View (optional)! 31 Date Storage Module: Variable Declarations! 32 Date Storage Module: Access Programs! 33 Date Storage Module: Auxiliary Functions! 34 Date Storage Module: Auxiliary Functions! 35 Output Functions! 36 Time storage module! 37 Output Functions! 38 stack With limited range and depth: Declarations! 40 stack With limited range and depth: Access Programs! 41 Stack: Auxiliary Functions! 42 Stack: Output variable functions! 43 Stack: Output variable functions! 44 Stack: Output variable functions! 45 What Can Be Done with TFM Documents! 46 Conclusions! 47

Middle Road Software

David Parnas, 2010 March 30 15:14

• 3/47! !

! ! ! !

TFM slides Iowa State.pages

Needed: A Way To Describe Software Without Writing Code. In 1969 my manager told me:

• We should not need to write code to tell a programmer

what the code they should write must do.

• A reviewer should be able to find out what a program is

supposed to do without studying the code.

• Someone who wants to use software should be able to

know what it does without reading the code. Later we learned that:

• If we have several interchangeable implementations, we

should be able to write down what they have in common.

Middle Road Software

David Parnas 2010 March 30 15:14

• 4 /47
• TFM slides Iowa State.pages

Software Reference Documentation Introductory documentation is designed to make it easy for a beginner to learn something completely new. Reference documentation is designed to make it easy for an expert to look up specific details. Contrast your first textbook on English with a Dictionary. This discussion is about reference documentation. It is not about introductory, sales, or FAQ documentation.

Middle Road Software

David Parnas 2010 March 30 15:14

• 5 /47
• TFM slides Iowa State.pages

Defining The Required Content Of Documents Everyone working on a project must know where to find specific information. Everything they should want to know should be in the documentation. As far as possible, nothing should be in two documents. We define every document as a representation of a mathematical relation.This tells us what information should be in a document but not how it should be represented. A Module Interface Document (MID) should define the value

• f output variables by a relation with the module history.

For deterministic modules, this is a function.

Middle Road Software

David Parnas 2010 March 30 15:14

• 6 /47
• TFM slides Iowa State.pages

This Talk Is Not About Tabular Expressions Tabular Expressions are multidimensional form of mathematical expressions. Usually tabular expressions are easier to read than conventional expression. Each expression is an indexed set of grids. Each grid is an indexed set of expressions. An expression may be either a conventional expression or a tabular expression of a type that has been previously defined. The definition of the meaning of a tabular expression is an equivalent conventional expression. This talk uses, but does not define, tabular expressions.

Middle Road Software

David Parnas 2010 March 30 15:14

• 7 /47
• TFM slides Iowa State.pages

Document Roles Engineering usage:

• A description states properties of a product; it may

include a mixture of incidental and required properties.

• A specification is a description that states only required

properties.

• A full specification is a specification that states all

required properties. The same notation may be used for all 3. These classifications are a matter of intent not notation. There is no such thing as a “specification language”.

Middle Road Software

David Parnas 2010 March 30 15:14

• 8 /47
• TFM slides Iowa State.pages

Obligations Of Those Who Agree On A Specification

• Implementers may either accept the task of implementing

that specification, or report problems with the specification and propose a revision; they may not accept the task and then (knowingly) build something that does not satisfy the specification.

• Users must be able to count on the properties stated in a
• specification. However, they must not base their work on

any properties mentioned in any other description unless those properties are implied by the specification.

• Purchasers are obligated to accept any product that

meets the specification that they agreed on. Other descriptions may be useful for understanding particular implementations.

Middle Road Software

David Parnas 2010 March 30 15:14

• 9 /47
• TFM slides Iowa State.pages

Software Design Issues Programs, Components and Modules Design Principles

• divide and conquer
• loose coupling
• separation of concerns
• encapsulation
• information hiding

Applying these principles requires us to document the interface information precisely and without revealing any internal information. Multiple-Interface Modules (upper face, lower face, restricted face, other interfaces)

Middle Road Software

David Parnas 2010 March 30 15:14

• 10/47
• TFM slides Iowa State.pages

Earlier Approaches To Module Interface Documentation Approaches to methods of writing module interface specifications can be divided into four classes:

• pragmatic, such as [Pa72a], [CP84], [CPS84]
• algebraic, following the pioneering work of Guttag[GH78]
• axiomatic, following the pioneering work of Zilles[LZ75]
• mixtures of the above.
• equivalent programs.

Middle Road Software

David Parnas 2010 March 30 15:14

• 11/47
• TFM slides Iowa State.pages

What’s Wrong With Giving An Equivalent Program May overspecify!

• bubble sort does not specify a sort.

Languages often undefined. (pseudo code). Often overly complex. Often lies rather than abstractions

• abstraction, one thing that represents many
• everything derivable from abstraction must be true of all it represents
• Otherwise it is a lie, and dangerous

Limitations often not described.

Middle Road Software

David Parnas 2010 March 30 15:14

• 12/47
• TFM slides Iowa State.pages

Strengths And Weaknesses Of Various Approaches Pragmatic approaches

• Work most of the time
• Major limitations in infrequently occurring cases.

Algebraic and Axiomatic Approaches

• Elegant
• Counter-Intuitive
• Fewer limitations than pragmatic but still limited.

Trace Assertion Approaches (TAM)

• Still Fewer Limitations
• Still counter-intuitive.
• Less elegant

Middle Road Software

David Parnas 2010 March 30 15:14

• 13/47
• TFM slides Iowa State.pages

Readability No guarantee that a document is readable. An approach can allow and help writers to produce easily used documents

• Directness: Evaluation not deduction
• no searching for applicable transformation rules
• direct evaluation of functions
• Abstraction: only observables are mentioned.
• All required observables are described
• Ability to distinguish the essential information from

incidental information

• A place for everything; everything in its place.

Middle Road Software

David Parnas 2010 March 30 15:14

• 14/47
• TFM slides Iowa State.pages

Axiomatic vs. Functional Aproaches Axiomatic approach

• Given a set of statements accepted as true (axioms)
• Given a set of rules of inference (transformations)
• Search for a sequence of applications of inference rules

to axioms or proven statements to answer a question. Functional Approach

• Given a set of expressions applying functions to variables
• Assign values to all variables.
• Evaluate functions using assigned values and earlier

results. Engineers -prefer evaluation (closed form).

Middle Road Software

David Parnas 2010 March 30 15:14

• 15/47
• TFM slides Iowa State.pages

What’s New In TFM The method described in this talk, TFM, deviates from past efforts in several significant ways:

• Not equational or axiomatic - evaluation of “closed form” expressions.
• Full use of multidimensional (tabular) expressions - same as other

documents but no special tables for TFM.

• Almost conventional logic [Pa93].
• Limitations of algebraic and axiomatic documents removed.
• Can document modules that communicate through global variables
• States the most often needed information directly
• Abstracts from all implementation details
• Clearly distinguishes the essential information from other information
• Allows the use of standard mathematical concepts
• Supports a strict (arbitrary) organization for the information to ease

retrieval and avoid duplication and inconsistency.

Middle Road Software

David Parnas 2010 March 30 15:14

• 16/47
• TFM slides Iowa State.pages

Communication With Software Modules Software modules have two distinct data structures.

• a hidden (internal) data structure
• a global data structure

Note that:

• The “value” of a function program is treated as a global variable.
• When programs communicate using parameters, the arguments are

placeholders for the shared/global variables that will be used.

• Often, the event is the invocation of one of the moduleʼs externally

accessible programs. A global variable that contains the name of the program invoked at an event, is a global variable, i.e. one of the inputs.

• Time,“cpu cycles consumed”, etc. which are often considered special, are

also easily considered as global variables and require no special treatment.

Shared/global variables are the fundamental way that modules communicate.

Middle Road Software

David Parnas 2010 March 30 15:14

• 17/47
• TFM slides Iowa State.pages

Events A software module may be viewed as a finite state machine

• perating at discrete points in time, which we call events.

At each event:

• reading some global variables (e.g. via input parameters), and
• changing its internal state, and
• changing the value of some of the global variables.

Remember: time is a global variable. An event is instantaneous, i.e the time between these activities cannot be observed by other components. There are no simultaneous events. If two events occur at the same time, they are a single event.

Middle Road Software

David Parnas 2010 March 30 15:14

• 18/47
• TFM slides Iowa State.pages

Event Descriptors Each element of the global data structure must have a unique identifier . “PGM” is reserved for the name of a program invoked, A full event descriptor specifies the values of every variable in the global data structure before and after the event. Abbreviated event descriptors contain only input/output variables. Example of an abbreviated event descriptor.

PGM ‘io ‘in io’

• ut’

name of program invoked in event value of io before the event value of in before the event value of io after the event value of out after the event

Middle Road Software

David Parnas 2010 March 30 15:14

• 19/47
• TFM slides Iowa State.pages

Traces A trace is a finite sequence of event descriptors; it describes a sequence of events. A subtrace of a trace T is a sequence of the event descriptors that is contained within a trace T. Prefix of T is a subtrace containing the first elements of T. A 5 element trace:

PGM ‘io1 ‘in2 io1’

• ut1’

name of program invoked value of io1 before the event value of in2 before the event value of io1 after the event value of out1 after the event name of program invoked value of io1 before the event value of in2 before the event value of io1 after the event value of out1 after the event name of program invoked value of io1 before the event value of in2 before the event value of io1 after the event value of out1 after the event name of program invoked value of io1 before the event value of in2 before the event value of io1 after the event value of out1 after the event name of program invoked value of io1 before the event value of in2 before the event value of io1 after the event value of out1 after the event

Note that “trace” is a purely formal concept. A history, is a trace that accurately describes all of the events that affected a module after its initialization.

Middle Road Software

David Parnas 2010 March 30 15:14

• 20/47
• TFM slides Iowa State.pages

Trace Function (TFM) Component Interface Documentation A TFM component interface document comprises:

• a complete description of the component’s inputs (their

type), and

• a complete description of the component’s outputs (their

type) , and

• a description of a set of relations, each one describing the

relation of the value of an output to the history of the events affecting or involving the component. Note that histories includes all past behavior including the actual outputs; this means that one can use information about both past outputs and past inputs to determine the possible output values after the last event in a trace.

Middle Road Software

David Parnas 2010 March 30 15:14

• 21/47
• TFM slides Iowa State.pages

When Is A Trace-based Document Complete? A TFM document is complete if there is a relation for every

• utput and the complete set of possible traces for which

the value of each output is defined is included in the domain of the corresponding relation. If we have a description of the set of possible traces, we can determine completeness. The domain of the description could also be a superset of that set.

Middle Road Software

David Parnas 2010 March 30 15:14

• 22/47
• TFM slides Iowa State.pages

When Is A Trace-based Document Consistent? Because each output is defined separately (dependent only

• n inputs and earlier values of other outputs), the

document is consistent if each individual relation is consistently defined. Using tabular notation, consistency of a function/relation definition is usually easy to establish.

Middle Road Software

David Parnas 2010 March 30 15:14

• 23/47
• TFM slides Iowa State.pages

What Is A TFM Specification? A TFM specification of a component M characterizes the set

• f traces that are be considered acceptable for M.

If

• any of the behaviors described in the specification as acceptable would be

considered unacceptable by users, or

• any user-acceptable behaviors are excluded by the document,

it is the purported specification that is incorrect. If an implementation shows behavior not allowed by a correct specification, the implementation is incorrect.

Middle Road Software

David Parnas 2010 March 30 15:14

• 24/47
• TFM slides Iowa State.pages

What Is A TFM Description? A TFM description of an implementation of a module M is a TFM document that characterizes the set of traces that are possible with that implementation. If the implementation exhibits any behavior not included in a document proposed as a complete description, or if the description describes behavior that never happens, it is the purported description that is incorrect.

Middle Road Software

David Parnas 2010 March 30 15:14

• 25/47
• TFM slides Iowa State.pages

When Is An Implementation Of A Module Correct? Two stages:

• Produce a description of the implementation’s behavior.
• Compare the description with the specification

In the comparison we determine:

• that the two documents match syntactically, i.e. that the

inputs and outputs match in name and type,

• that each relation in the description is a subset of the

corresponding relation in the specification,

• that the domain of each relation in the description

contains the domain of the corresponding relation in the specification.

Middle Road Software

David Parnas 2010 March 30 15:14

• 26/47
• TFM slides Iowa State.pages

Modules That Create More Than One Object

• Viewing a component as creating many objects is only

useful if the objects are independent - no side-effects.

• One can prepare much of the interface documentation as

if the component created only one object.

• Each object must have a identifier.
• The identifier is prepended to the name of the operation in

the style of “OO” languages.

• Additional objects are named as operands in the same

way as operands of other types.

• Each object has a separate trace,“T.<object name>”.
• If an operation on one object will affect another, the group

must be treated as a single object.

Middle Road Software

David Parnas 2010 March 30 15:14

• 27/47
• TFM slides Iowa State.pages

Primitive Functions On Event Descriptors If e is an event descriptor and “V” is the unique name of a variable,

• “ ‘V(e) ” denotes the value of V immediately before the

event described by e

• “ V’(e) ” denotes the value of V immediately after that

event

• PGM(e) is the name of the program invoked at that event

(if any). All of this information is in the event descriptor for e and consequently, in the trace.

Middle Road Software

David Parnas 2010 March 30 15:14

• 28/47
• TFM slides Iowa State.pages

Primitive Functions On Traces

L(T) (length) (<trace> ! <integer>)

• L(T) is the number of event descriptors in T; L(T) is 0 if T is empty.

r(T) (most recent) (<trace> ! <event descriptor>)

• r(T) is the last (most recent) event descriptor in the trace
• (T) (oldest) (<trace> ! <event descriptor>)
• o(T) is the oldest event descriptor in the trace; it is undefined if L(T) = 0.

p(T) (precursor) (<trace> ! <trace>) p(T) ≡

L(T) = 0 L(T) = 1 _ L(T) > 1 T2 | T = T2.r(T)

There are more in the papers.

Middle Road Software

David Parnas 2010 March 30 15:14

• 29/47
• TFM slides Iowa State.pages

Useful Function Generators

• P is a predicate on event descriptors.
• T is a trace.

ex(P)(T) (exists)

ex(P)(T) is true if and only if T contains an event descriptor that satisfies P .

• st(P)(T) (oldest such that)

et(P)(T) (extracted trace) irst(P)(T) (index recent such that)

iost(P)(T) (index oldest such that

There are more in the papers.

Middle Road Software

David Parnas 2010 March 30 15:14

• 30/47
• TFM slides Iowa State.pages

Date Storage Module: Schematic View (optional) year day month value in2 in1 PGM

Middle Road Software

David Parnas 2010 March 30 15:14

• 31/47
• TFM slides Iowa State.pages

Date Storage Module: Variable Declarations Output Variables

Variable Name Type <id>.day <integer> <id>.month <integer> <id>.year <integer> <id>.Value <integer>

Input Variables

Variable Name Type PGM <program name> in1 <integer> in2 date

Middle Road Software

David Parnas 2010 March 30 15:14

• 32/47
• TFM slides Iowa State.pages

Date Storage Module: Access Programs

Program Name Oname Value in1 in2 Abbreviated Event Descriptor SETDAY <id> <integer> (PGM:SETDAY, ‘in, day’) SETMONTH <id> <integer> (PGM:SETMONTH, ‘in, month’, ) SETYEAR <id> <integer> (PGM:SETYEAR, ‘in, year’) GETDAY <id> <integer> (PGM:GETDAY, Value’, ‘day) GETMONTH <id> <integer> (PGM:GETMONTH, Value’, ‘month) GETYEAR <id> <integer> (PGM:GETYEAR, Value’, ‘year) NEWDATE <id> <id> (PGM:NEWDATE, ‘<in2>, <in2>’) DELETEDATE <id> (PGM:DELETEDATE, ‘<in2>, <in2>’) COPYDATE <id> (PGM:COPYDATE, ‘<in2>)

Middle Road Software

David Parnas 2010 March 30 15:14

• 33/47
• TFM slides Iowa State.pages

Date Storage Module: Auxiliary Functions

day(T) ≡

(T = _) ∨ (T = _) ∨ PGM(r(T) = NEWDATE ¬ (PGM(r(T)) = SETDAY) ‘in(r(T)) ¬ (PGM(r(T)) = COPYDATE) day(‘in2(r(T)) ¬ (PGM(r(T)) = DELETEDATE) ¬(T = _) ∧ ¬(PGM(r(T)) = SETDAY ∨ ∨ ∨ ¬(T = _) ∧ ¬(PGM(r(T)) = SETDAY ∨ PGM(r(T)) = COPYDATE ∨ PGM(r(T)) = DELETEDATE ∨ PGM(r(T) = NEWDATE ) day(p(T))

month(T) ≡

(T = _) ∨ = _) ∨ PGM(r(T) = NEWDATE ¬ (PGM(r(T)) = SETMONTH) ‘in(r(T)) ¬ (PGM(r(T)) = COPYDATE) month(‘in2(r(T)) ¬ (PGM(r(T)) = DELETEDATE) ¬(T = _) ∧ ¬(PGM(r(T)) = SETMONTH ∨ ∨ ∨ ¬(T = _) ∧ ¬(PGM(r(T)) = SETMONTH ∨ PGM(r(T)) = COPYDATE ∨ PGM(r(T)) = DELETEDATE ∨ PGM(r(T) = NEWDATE ) month(p(T))

Middle Road Software

David Parnas 2010 March 30 15:14

• 34/47
• TFM slides Iowa State.pages

Date Storage Module: Auxiliary Functions

year(T) ≡

(T = _) ∨ = _) ∨ PGM(r(T) = NEWDATE ¬ (PGM(r(T)) = SETYEAR) ‘in(r(T)) ¬ (PGM(r(T)) = COPYDATE) year(‘in2(r(T))) ¬ (PGM(r(T)) = DELETEDATE) ¬(T = _) ∧ ¬(PGM(r(T)) = SETYEAR ∨ ∨ ∨ ¬(T = _) ∧ ¬(PGM(r(T)) = SETYEAR ∨ PGM(r(T)) = COPYDATE ∨ PGM(r(T)) = DELETEDATE ∨ PGM(r(T) = NEWDATE ) year(p(T))

Value (T) ≡

PGM(r(T)) = GETDAY day’(T) PGM(r(T)) = GETYEAR year’(T) PGM(r(T)) = GETMONTH month’(T) ¬( PGM(r(T)) = GETDAY ∨ PGM ∨ ) ¬( PGM(r(T)) = GETDAY ∨ PGM (r(T)) = GETYEAR ∨ PGM(r(T)) = GETMONTH )

Middle Road Software

David Parnas 2010 March 30 15:14

• 35/47
• TFM slides Iowa State.pages

Output Functions

<id>.day ≡ day(T<id>) <id>.month ≡ month(T<id>) <id>. year ≡ year(T<id>) <id>.Value ≡ Value(T<id>)

Middle Road Software

David Parnas 2010 March 30 15:14

• 36/47
• TFM slides Iowa State.pages

Time Storage Module Output Variables

Variable Name Type hr <integer> min <integer>

Access Programs

Program Name ‘in Abbreviated Event Descriptor SET HR <integer> (PGM:SET HR, ‘in, hr’) SET MIN <integer> (PGM: SET MIN, ‘in, min’) INC (PGM:INC, hr’, min’) DEC (PGM:DEC, hr’, min’)

Middle Road Software

David Parnas 2010 March 30 15:14

• 37/47
• TFM slides Iowa State.pages

Output Functions hr(T) ≡

PGM(r(T)) = S )) = SET HR ! 0 ! ʼin 0 ! ʼin(r(T ! ʼin(r(T)) < 24 ʻin(r(T)) PGM(r(T)) = S )) = SET HR ! ¬ (0 ! i ¬ (0 ! in(r(T (0 ! in(r(T)) < 24) hr((p(T))) PGM(r(T)) = S (r(T)) = SET MIN MIN IN hr((p(T))) PGM min(p(T))= (p(T))= 59 ! hr(p(T))= 23 PGM(r(T)) = INC ! min(p(T))= (p(T))= 59 ! ¬ hr(p(T))= 23 1+ hr((p(T))) ¬ (min(p(T (min(p(T))=5 (p(T))=59) hr((p(T))) PGM(r(T)) = DEC ¬ (min(p(T (min(p(T))= (p(T))= 0) hr((p(T))) PGM(r(T)) = DEC ! min(p(T))= (p(T))= 0 ! ¬ (hr(p(T)))= 0 hr((p(T)))-1 ! min(p(T))= (p(T))= 0 ! hr(p(T))= 0 23 T= T= _

Middle Road Software

David Parnas 2010 March 30 15:14

• 38/47
• TFM slides Iowa State.pages

More Output Functions

min(T) ≡ PGM(r(T (r(T)) = S )) = SET HR min(p(T)) PGM(r(T)) = SET MIN IN ! 0 ! ʻin(r(T)) ! 59 ʻin(r(T)) PGM(r(T)) = SET MIN IN ! ¬ (0 ! ʻin(r(T)) ! 59) min(p(T)) PGM(r(T)) = INC ! min(p(T)) = 59 PGM(r(T)) = INC ! ¬ (min(p(T))=59) min(p(T)) + 1 PGM(r(T)) = DEC ! ¬ (min(p(T))= 0) min((p(T))) −1 PGM(r(T)) = DEC ! min(p(T))= 0 59 T= T= _ T= _

Middle Road Software

David Parnas 2010 March 30 15:14

• 39/47
• TFM slides Iowa State.pages

Stack With Limited Range And Depth: Declarations

Output Variables Variable Name Type top <integer> depth <integer> exc {none, range, depth, empty} Value <integer> Input Variables Variable Name Type PGM {push, pop, top, depth} in <integer> Parameters Parameter Name Type d <integer> LB <integer> UB <integer>

Middle Road Software

David Parnas 2010 March 30 15:14

• 40/47
• TFM slides Iowa State.pages

Stack With Limited Range And Depth: Access Programs

Program Name ʻValue in Abbreviated Event Descriptor PUSH <integer> (PGM:PUSH, ʻin, topʼ, depthʼ,excʼ) POP (PGM:POP, topʼ, depthʼ, excʼ) TOP <integer> (PGM:TOP, Valueʼ, excʼ) DEPTH <integer> (PGM:DEPTH, Valueʼ)

The above is for explanation only. It is derivable from the other parts of the specification and is not included

Middle Road Software

David Parnas 2010 March 30 15:14

• 41/47
• TFM slides Iowa State.pages

Stack: Auxiliary Functions

inrange(i) ≡ LB " i " UB noeffect(e)≡ ! (PGM(e)=PUSH ∧ (¬inrange(‘in(e)))) ∨ (PGM(e) = TOP) ∨ (PGM(e) = DEPTH) full(T) ≡ (depth(T) = d) empty(T) ≡ (depth(T) = 0) unpush (T,n) ≡ T = _ _ noeffect(r(T)) t(r(T)) (T)) unpush(p(T), n) r(T) = push ful full(p(T)) unpush(p(T), n) ¬(T = _) ¬noeffect(r(T)) r(T) = push ∧ ¬ (fu ¬ (full(p(T)) n = 1 p(T) ¬(T = _) ∧ ¬noeffect(r(T)) ∧ ∧ ¬ (fu ¬ (full(p(T)) ∧ n > 1 unpush(p(T), n-1) ∧ r(T) = pop ∧ p ∧ empty(p(T ty(p(T)) unpush(p(T), n) r(T) = pop ∧ p ∧ ¬ empty(p(T ty(p(T)) unpush(p(T), n+1)

Middle Road Software

David Parnas 2010 March 30 15:14

• 42/47
• TFM slides Iowa State.pages

Stack: Output Variable Functions

top(T) ≡ T = _ PGM(r(T) = POP top(unpush(p(T), 1)) ¬(T = _ ) PGM(r(T) = PUSH in(r(T)) ¬(T = _ ) ∧ PGM(r(T) = TOP top(p(T)) PGM(r(T) = DEPTH top(p(T)) Value(T) ≡ PGM(r(T))=TOP top(p(T)) PGM(r(T))=DEPTH depth(p(T)) PGM(r(T))=PUSH PGM(r(T))=POP

Middle Road Software

David Parnas 2010 March 30 15:14

• 43/47
• TFM slides Iowa State.pages

Stack: Output Variable Functions

depth(T) ≡ T = _ noeffect(r(T)) depth(p(T)) (T ≠ _) PGM(r(T))=POP depth(p(T)) = 0 (T ≠ _) ∧ ¬ noeffect(r(T)) ∧ PGM(r(T))=POP ∧ depth(p(T)) ≠ 0 depth(p(T)) - 1 ∧ ¬ noeffect(r(T)) ∧ PGM(r(T))=PUSH ∧ depth(p(T))= d d PGM(r(T))=PUSH ∧ depth(p(T)) ≠ d depth(p(T)) + 1

Middle Road Software

David Parnas 2010 March 30 15:14

• 44/47
• TFM slides Iowa State.pages

Stack: Output Variable Functions

exc(T) ≡ ¬inrange( ¬inrange(ʻin(r(T))) range PGM(r(T))=PUSH ∧ inrange(ʻin(r(T))) ∧ depth(T) = d depth inrange(ʻin(r(T))) ∧ ¬ depth(T) = d none (PGM(r(T))=POP ∨ PGM(r(T))= TOP) depth(T pth(T) = 0 empty (PGM(r(T))=POP ∨ PGM(r(T))= TOP) ∧ ¬ depth(T epth(T) = 0 none PG PGM(r(T))=DEPTH none

Middle Road Software

David Parnas 2010 March 30 15:14

• 45/47
• TFM slides Iowa State.pages

What Can Be Done With TFM Documents Discuss them with users Reviewers with substance to work on Allow a user to review by simulation. Give them to a programmer to implement. Give them to testers, who

• use them to generate test programs, chose test cases
• use them to evaluate results

Give them to maintainers

Middle Road Software

David Parnas 2010 March 30 15:14

• 46/47
• TFM slides Iowa State.pages

Conclusions Writing precise documentation will never be easy but

• Simple cases are simple.
• Complex cases remain complex. (reconsider the design)
• The key to simple specifications remains good design.

TFM seems to be as good as we have. Take it as a challenge!

Middle Road Software

David Parnas 2010 March 30 15:14

• 47/47
• TFM slides Iowa State.pages