Middle Road Software Middle Road Software Module Interface Documentation - Using The Trace Function Method Outline (TFM) Review of basic software documentation principles David Lorge Parnas Modules and how they communicate Marius Dragomiroiu Events and event descriptors Traces Abstract The Trace Function Method (TFM) for documenting (both describing and What the document looks like specifying) interfaces for information hiding modules and components is described. We begin by explaining the motivation for the method. The concepts Completeness and consistency of event, event descriptor, and trace are defined. Basic functions on event Examples descriptors and traces are introduced. Finally, the method is illustrated on some simple examples. 1/47 ! ! ! ! ! ! 2/47 ! ! ! ! ! ! David Parnas, 2010 March 30 15:14 � � David Parnas, 2010 March 30 15:14 � � � � � � TFM slides Iowa State.pages � � � � TFM slides Iowa State.pages Middle Road Software Middle Road Software When is an implementation of a module correct? ! 26 Needed: A Way To Describe Software Without Writing Code. Needed: a way to describe software without Writing code. ! 4 Modules that Create more than one Object ! 27 Software Reference Documentation ! 5 Primitive Functions on Event Descriptors ! 28 Defining the required content of documents ! 6 In 1969 my manager told me: Primitive Functions on Traces ! 29 This Talk is Not about tabular expressions ! 7 Useful Function Generators ! 30 Document Roles ! 8 •We should not need to write code to tell a programmer Date Storage Module: Schematic View (optional) ! 31 Obligations of Those who Agree on a Specification ! 9 what the code they should write must do. Date Storage Module: Variable Declarations ! 32 Software Design Issues ! 10 Date Storage Module: Access Programs ! 33 Earlier approaches to module interface documentation ! 11 •A reviewer should be able to find out what a program is Date Storage Module: Auxiliary Functions ! 34 What’s wrong with Giving an Equivalent Program ! 12 Date Storage Module: Auxiliary Functions ! 35 supposed to do without studying the code. Strengths and Weaknesses of Various Approaches ! 13 Output Functions ! 36 Readability ! 14 Time storage module ! 37 •Someone who wants to use software should be able to Axiomatic vs. functional Aproaches ! 15 Output Functions ! 38 know what it does without reading the code. What’s new in TFM ! 16 stack With limited range and depth: Declarations ! 40 Communication with Software Modules ! 17 stack With limited range and depth: Access Programs ! 41 Later we learned that: Events ! 18 Stack: Auxiliary Functions ! 42 Event descriptors ! 19 Stack: Output variable functions ! 43 •If we have several interchangeable implementations, we Traces ! 20 Stack: Output variable functions ! 44 should be able to write down what they have in common. Trace Function (TFM) Component Interface Documentation ! 21 Stack: Output variable functions ! 45 When is a trace-based document complete? ! 22 What Can Be Done with TFM Documents ! 46 When is a trace-based document consistent? ! 23 Conclusions ! 47 What is a TFM specification? ! 24 What is a TFM description? ! 25 3/47 ! ! ! ! ! ! David Parnas, 2010 March 30 15:14 � � � � � � TFM slides Iowa State.pages David Parnas 2010 March 30 15:14 � � � � � 4 /47 � � � � � TFM slides Iowa State.pages
Middle Road Software Middle Road Software Software Reference Documentation Defining The Required Content Of Documents Introductory documentation is designed to make it easy for Everyone working on a project must know where to find a beginner to learn something completely new. specific information. Reference documentation is designed to make it easy for Everything they should want to know should be in the an expert to look up specific details. documentation. Contrast your first textbook on English with a Dictionary. As far as possible, nothing should be in two documents. This discussion is about reference documentation. We define every document as a representation of a mathematical relation.This tells us what information should It is not about introductory, sales, or FAQ documentation. be in a document but not how it should be represented. A Module Interface Document (MID) should define the value of output variables by a relation with the module history. For deterministic modules, this is a function. David Parnas 2010 March 30 15:14 � � � � � 5 /47 � � � � � TFM slides Iowa State.pages David Parnas 2010 March 30 15:14 � � � � � 6 /47 � � � � � TFM slides Iowa State.pages Middle Road Software Middle Road Software This Talk Is Not About Tabular Expressions Document Roles Tabular Expressions are multidimensional form of Engineering usage: mathematical expressions. Usually tabular expressions are •A description states properties of a product; it may easier to read than conventional expression. include a mixture of incidental and required properties. Each expression is an indexed set of grids. •A specification is a description that states only required properties. Each grid is an indexed set of expressions. •A full specification is a specification that states all An expression may be either a conventional expression or a required properties. tabular expression of a type that has been previously The same notation may be used for all 3. defined. These classifications are a matter of intent not notation. The definition of the meaning of a tabular expression is an equivalent conventional expression. There is no such thing as a “specification language”. This talk uses, but does not define, tabular expressions. David Parnas 2010 March 30 15:14 � � � � � 7 /47 � � � � � TFM slides Iowa State.pages David Parnas 2010 March 30 15:14 � � � � � 8 /47 � � � � � TFM slides Iowa State.pages
Middle Road Software Middle Road Software Obligations Of Those Who Agree On A Specification Software Design Issues •Implementers may either accept the task of implementing Programs, Components and Modules that specification, or report problems with the Design Principles specification and propose a revision; they may not accept the task and then (knowingly) build something that does • divide and conquer not satisfy the specification. • loose coupling • separation of concerns •Users must be able to count on the properties stated in a • encapsulation specification. However, they must not base their work on any properties mentioned in any other description unless • information hiding those properties are implied by the specification. Applying these principles requires us to document the interface information precisely and without revealing any •Purchasers are obligated to accept any product that internal information. meets the specification that they agreed on. Multiple-Interface Modules (upper face, lower face, Other descriptions may be useful for understanding restricted face, other interfaces) particular implementations. David Parnas 2010 March 30 15:14 � � � � � 9 /47 � � � � � TFM slides Iowa State.pages David Parnas 2010 March 30 15:14 � � � � � 10/47 � � � � � TFM slides Iowa State.pages Middle Road Software Middle Road Software Earlier Approaches To Module Interface Documentation What’s Wrong With Giving An Equivalent Program Approaches to methods of writing module interface May overspecify! specifications can be divided into four classes: • bubble sort does not specify a sort. •pragmatic, such as [Pa72a], [CP84], [CPS84] Languages often undefined. (pseudo code). •algebraic, following the pioneering work of Guttag[GH78] Often overly complex. •axiomatic, following the pioneering work of Zilles[LZ75] Often lies rather than abstractions •mixtures of the above. • abstraction, one thing that represents many • everything derivable from abstraction must be true of all it represents •equivalent programs. • Otherwise it is a lie, and dangerous Limitations often not described. David Parnas 2010 March 30 15:14 � � � � � 11/47 � � � � � TFM slides Iowa State.pages David Parnas 2010 March 30 15:14 � � � � � 12/47 � � � � � TFM slides Iowa State.pages
Recommend
More recommend
