Precise Documentation: The Key To Better Software David ...colloq/new/David_Parnas_slides.pdfdeal of room for improvement by researchers who are willing to invest time in truly difﬁcult

Precise Documentation: The Key To Better Software

David Lorge ParnasAbstract

If I had to identify a single prime cause for the sorry “state of the art” in software development, it is documentation. Failure to document designs properly, reduces efficiency in every phase in a software product’s “lifetime” and is a major cause of the low quality software that we see today.

If I say, “documentation” to software developers, they assume that I am discussing a collection of wordy, unstructured, introductory descriptions. They picture thousands of pages that nobody trusts and nobody wanted to write. If I say, “documentation” to Engineers in more traditional disciplines, they envision precise blueprints, circuit diagrams, and mathematical component property specifications. Developers do not know how to produce equivalent documents for software.

Among the benefits of good documentation would be: easier reuse of old designs, better communication about requirements, easier integration of separately written modules, more effective inspection, more effective testing, and more efficient maintenance. The role of precise (mathematically based) documents in each of these activities will be illustrated and explained. Some recent improvements in software documentation methods will be shown and some important research problems will be described.

The approach described has been used in “real” products and can be used today but there is a great deal of room for improvement by researchers who are willing to invest time in truly difficult problems.

Middle Road Software, Inc.

1/61David Parnas 16 March 2010 00:49 Iowa State DL slides.pages.

1. -------------------------------------------My First Software Experience 32. ---------The Symptoms: What Goes Wrong With Software Projects 43. ---------------------------------------------Widespread Belief in Magic 54. -----------------------------------Pretend Process Improvement (PPI) 65. -------------------------------------Why Real Improvement is Difficult 76. -------------------------------Why Real Improvement Should Be Easy 87. --------------Dilbert also believes that documentation is important. 98. -------------------------------------------------------The Full Message 109. ------------------------------------------What Is Meant by “Document” 1110. --------------------------------------Steps Towards Better Documents 1211. ----------------------A Preliminary Example: Dell Keyboard Checker 1312. ----------------------------------Requirements for Keyboard Checker 1413. -----------------------------------------------No Theoretical Advantage 1514. ------------------------------------------Documents Are Not Programs 1615. -----------------------------------------Practical Experience (30 years) 1716. -------------------The Role of Documents in Traditional Engineering 1817. ----------------------More About What I Mean by “Documentation”? 1918. -----------------What We Must Do To Improve Software Documents 2019. -------------------------------Some Basic Documentation Guidelines 2120. ----------------------------------------------------------Document Roles 2221. -Is Mathematical Documentation the Same as “Formal Methods”? 2322. ----------------------------------------------Is This “Formal Methods”? 2423. --------------------------------This Too is A Mathematical Expression 2524. -----------------------------------------------------------A Circular Table 2625. ------------------------------------------Definition of a Circular Table I 2726. ------------------------------------------Definition of a Circular Table II 2827. -----------------------------------------------Table With Same Meaning 2928. ------------------Content Definitions For Documents: Why and How 3029. ----------------------------------------------------The Main Documents 3130. -----------------------------Document Information Content (Informal) 3231. ----------------Example: Functional Definition of Document Content 3332. ---------------Why we need complete requiquirements documents: 3433. --------Why Programmers Should Not Make User-visible Decisions 35

34. ---------------------------------------------------A Small Success Story 3635. -----------------Requirements Documents: Readers Digest Version: 3736. ---------------------Documentation For “Programming in the Large” 3837. -----------------------------------------------Modules vs. Components 3938. ------------------Designing and Documenting the Module Structure 4039. -----------------------------------------------------------Larger Systems 4140. --------------------------------------------Group Modules Into Classes 4241. ---------------------------------Documentation of a Module Structure 4342. -------------------------------------------------Per-Module Documents 4443. -----------------------------------------------------------------Interfaces 4544. ----------------------------Surprising Observations about Interfaces. 4645. ----------------------------------------------------------Interface Design 4746. ------------------------------------------------Interface Documentation 4847. --------------------------Extract from Module Interface Document - I 4948. -------------------------Extract from Module Interface Document - II 5049. -------------------------------------------------------The Uses Structure 5150. -----------------------------Designing for Extension and Contraction 5251. ---------------------------------Documentation of the Uses Structure 5352. -----------------------------Display Form of Program Documentation 5453. -----------------------------------------------------------Sample Display 5554. -------------------------------------------Our Code Inspection Process 5655. ----------------------Effectiveness of Document Support Inspection 5756. -------------------------------------------------------The Bottom Lines: 5857. ---------------------Management’s Role in Document Driven Design 5958. ------------------------------------------------------Research Problems 6059. ----------------------------------------------------------------Thank You 61

Middle Road Software, Inc.

2/61David Parnas 16 March 2010 00:49 management slides

My First Software Experience

Developed a software simulator for logic design courseUsed for many years by EE students in big projects.Never simulated a correctly described design incorrectly!Secret of success:

• Intuitive, but correct, use of information hiding to separate concerns

• One-man project.

Problems: • Error messages

• Unmaintainable because of lack of documentation

• Couldn’t fix the first problem!

Middle Road Software

3/61

David Parnas 16 March 2010 00:49 management slides

The Symptoms: What Goes Wrong With Software Projects • Developers unclear about module responsibilities(gaps, duplication)

• Developer’s work does not integrate easily

• “Mythical Man Month” effect

• “Ripple” effect

• Poor design decisions not found until code is tested, in use, or changed.

• Inspections of code are not effective - many errors not found.

• Testing does not find faults - important test cases overlooked

• System doesn’t meet the real requirements

• Maintaining software, correcting errors/updating, very expensive

Though old, these problems are still real and costly.There are some new (and old) ideas that can help.We have to first understand the cause, then seek a cure.


4/61


Widespread Belief in Magic • We can’t document the required behaviour but we expect

to meet the requirements.

• We can’t document the interfaces but we expect the components to function properly together.

• We don’t know what the interfaces are or will be but we can write programs as if they won’t change.

• We can’t document our component design, but we can have a design review.

• Nobody can understand our software, but we can expect you to review it effectively.

• If we say we do it, we do do it (ISO, CMMI).

• Even if we can’t define our notation, we can use it to communicate precisely! (UML, Statecharts, Z)


5/61


Pretend Process Improvement (PPI)

Real improvement seems to be too hard!


6/61


Why Real Improvement is Difficult“Nobody” does it that way

• “Nobody” builds really good software (error free, easily maintained)

We don’t have time to write documents that nobody reads.

• “Never have time at the start, always have time at the end” (B.O. Evans)

• Make them useful and they will be read!Dilbert’s View:

“I have no idea how to do that” (Ph.D. developer, author)

• Nobody taught you how!


7/61


Why Real Improvement Should Be Easy

Payback: • The effort put in to useful documents is not lost but paid back. Without

documentation people often duplicate an inquiry but come to different answers.

• People do not interrupt each other as much. (Mythical Man Month Effect)

• Information quality improved because of review

• Design decisions are better because they are conscious and reviewed.

It can be taught. • Better to teach from the beginning

• Habit breaking requires follow-up, reviews, and coaching

Try it youʼll like it.Would be better with tools.


8/61


Dilbert also believes that documentation is important.


9/61


The Full Message

Failure to document software well is the source of the problems that we have with software. • Precise complete requirements documents would constrain the

programmer properly.

• Documentation can reduce the “mythical man month problem”.

• Information hiding reduces the “ripple effect” if interfaces are documented

• Documentation is essential for effective design reviews.

• Documentation support testing.

• Documentation make inspection more effective.

• Documentation make maintenance easier.

The question is “Can we produce better documents?

• The answer is “Yes, we can!”.


10/61


What Is Meant by “Document”

A record of design decisions that is binding, i.e. a restriction of future decisions.To be as useful as possible these documents must be:

• Accurate

• Consistent

• Complete (all required decisions fully documented).

Informal introductions/explanations are not documents in this sense. Vague documents are like vague contracts they may be worse than having no documents at all.


11/61


Steps Towards Better Documents

Use mathematics to get precision.Use mathematics to make checking and testing tools possible.Use tabular expressions to get readability and structure.Use rigid documentation rules to make it easy to find the information. (View as an information retrieval system). Build tools to make useful documents even more useful. Build tools to make it easier to produce good documents.The last three items are opportunities for researchers.


12/61


A Preliminary Example: Dell Keyboard Checker

In daily use in Limerick for many years.Believed to be completely correct.Two documents totaling 21 pages (English). • ambiguities

• missing cases

• errors

Posed as a challenge by skeptical managerAll information could be expressed in one page • revealed errors in program and documents

• much more precise and easily used.

• served as input to testing and inspection.


13/61


Requirements for Keyboard Checker


14/61


No Theoretical Advantage

Just practical advantages: • fewer errors

• checkability

• ease of reference.


15/61


Documents Are Not Programs

They must describe mappings from input to output.They must not describe steps in a computation process.They must not provide information that should not be in the document1. They must provide the information that the intended readership needsOur documents are mathematical expressions describing a function that maps an input to an output.


16/61

1 Content definitions for documents will be discussed later.


Practical Experience (30 years)

US military aircraft (projects still ongoing) • Answer any requirements question looking at ≤ 7 pages.

Nuclear Plants (ongoing) • 218 errors found in code that had been tested for six years.

• no further errors found in more than 15 years of use.2

Management Information Systems for Bell Labs. (?) • 14 “copycat” projects in first year

• shortest on-site testing time on record

Mobile Telephone connection software (base station) • Collected information that was distributed around the world into one easily

referenced document. Information very hard to get.


17/61

2 As of several yeaers ago.


The Role of Documents in Traditional Engineering

Engineers design through documentation.Documents record key design decisions.

• to enable review

• to guide the development

• to assist in inspection

• to inform in maintenance

Documents are binding on everyone and fully controlled.Documents are precise documents that use mathematics.Documents are not introductions or tutorials,Documents are not extracted comments (javadoc).Documents show “separation of concerns”.


18/61


More About What I Mean by “Documentation”?

Practical tool, not just a theoretical achievement and a demonstration of diligence.They must have the following properties.

•Authoritative repository of information

•Usable as a quick and reliable reference by developers, reviewers, maintainers, users

•Easier to use for retrieving information than the code.

•Structured to avoid inconsistency

•Quicker and more authoritative than trial executions

•Useful before, during, and after the coding.

We have only succeeded if developers use the methods.


19/61


What We Must Do To Improve Software Documents

Accuracy, precision, and consistency can be improved by using mathematics.Consistency, completeness, ease of reference can be improved by tabular notation and rigid organization.Consistency and ease of finding information are improved by having content definitions for each document.


20/61


Some Basic Documentation Guidelines

Never mix reference documents with introductions.Never rely on words; they will never be precise enough.Mathematics is the only way to be precise, but

• expressions must be simple and easily parsed

• Interpretation should be direct (closed form).

Only relevant information should be included and this information should be stated as directly as possible. Each item of information should be in only one place and everyone should know where it will be put/found .These are all easier said than done.


21/61


Document Roles

Engineering usage:•A description contains 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.

Distinction based on way document used, not content.The same notation may be used for all 3. • This has confused many researchers.

• These classifications are a matter of intent not notation.

• There is no such thing as a “specification language”.


22/61


Is Mathematical Documentation the Same as “Formal Methods”?

No! The differences are: • Information organized for easy retrieval.

• No new mathematics - classical concepts suffice.

• Not modeled on philosophers’ view of logic

• Engineering style of mathematics (“closed-form” solutions)

• Not axiomatic - users evaluate expressions, not derive

• Not intended for automatic verification (possible in theory).

• Proof is not the main goal (but possible in theory).

• Documents are not programs

Attention to authors and audiences - who needs what.Documentation is the end, math the means to that end


23/61


Is This “Formal Methods”?Ticket Price 1 Passenger 2 Passengers 3 - 5 Passengers 6 or more Passengers

0 - 100

101 - 200

201 - 300

301 and more

35 45 55 65

40 50 60 70

45 55 65 75

50 60 70 70 + 10 per passenger

How about this?

P=1 P=2 2 < P < 6 P > 5

0 < T ≤ 100

100 < T ≤ 200

200 < T ≤ 300

T > 300

35 45 55 65

40 50 60 70

45 55 65 75

50 60 70 70 + 10 ×(P-5)

The above is a tabular mathematical expression.


24/61


This Too is A Mathematical Expression

BMIT[1] p<

88

88!

p<

110

110

!p<

121

121

!p<

132

132

!p<

154

154

!p<

176

176

!p<

198

198

!p<

220

220

!p<

110

242

!p<

265

p>

265

T[4] T[0] T[2]

1.9!m<2 very talll

1.8!m<1.9 talll

1.7!m<1.8 avg

1.6!m<1.7 middle

1.5!m<1.6 short

m!1.5 very short

k<

4040! k< 50

50!k< 55

55!k< 60

60!k< 70

70!k< 80

80!k< 90

90!

k<

100

100

!k<

110

110

!k<

120

k>

120T[3]

underweight low borderline

normal low

overweight

overweight very

overweightOBESE!


25/61


A Circular Table

The meaning of such tables must be defined.


26/61


Definition of a Circular Table I1. Constituents

• integer: n 3

• grid T0

• predicate grid set TT

2. Auxiliary functions

Proper and select are defined in Section 4.

3. Restriction schema4

n>0 ∧ 1 ∈ IndexSet(TT) ∧

(∀i, k, s1, … sk, ((i,s1, … sk)∊ IndexSet(TT))→(integer(i) ∧ i>0 ∧ i≦n ∧ k=i-1)) ∧

(∀i, x, s1, … si-1, (i>0 ∧ i<n ∧ ((i,s1, … si-1) ∊ IndexSet(TT)) ∧ x ∊ IndexSet(T[i,s1, … si-1])) ↔ ((i+1,s1, …si-1, x) ∈ IndexSet(TT))) ∧

(∀i, s1, … sn, ((n,s1, … sn)∊ IndexSet(TT) ∧ i ∈ IndexSet(T[n,s1,… sn]) ↔ (s1, … sn, i) ∊ IndexSet(T0) )) ∧

Proper(T1) ∧ (∀i,s1, … si-1, ((i,s1, …si-1) ∈ IndexSet(TT)) → Proper(T[i,s1, …si-1],T[i-1,s1, … si-2][si-1]))


27/61

3 In the example, n (one less than the number of levels) is 3. 4 The restriction asserts that there is at least one predicate grid ( with index = 1), describes the form

of each index, establishes the ring structure in the grid indices, constrains the index set of T0 and as-serts that each predicate grid will be proper.


Definition of a Circular Table II4. Evaluation schema for an assignment that is complete for T

We define an indexed set of expressions, Si, by

S1 = select(eval(T1)) S2 = select(eval(T[2, S1])) S3 = select(eval(T[3,S1,S2])) ・・・ Sn = select(eval(T[n, S1, S2, S3, ・・・, Sn-1])

The evaluation schema is

T0[S1, S2,・・・, Sn].


28/61


Table With Same Meaning As Circular Example

The drawing is irrelevant because of the indices.


29/61


Content Definitions For Documents: Why and How

Organizations often specify the format of a document, but they rarely specify the content.We need a content definition to • know what to put where

• check for completeness.

Each document describes some mathematical relations.Each document has different ranges and domainsContent definition= meaning of the relation (which pairs)Content definitions say NOTHING about format, structure, notation, etc.


30/61


The Main Documents

Document Writers Readers/Users

Software Requirements Document

User reps, UI experts, app l icat ion exper ts , contro l led hardware experts

Authors of module guide and module interface specifications, (Software “Architects”)

Module Guide Software “Architects” All Developers

Module Interface Specifications

Software “Architects” Developers who implement or use the module

Program Uses Structure Software “Architects” Component Designers, Programmers

Module Implementation Design Document

Component Designers Programmers implementing component

Display Method Program Documentation

P r o g r a m m e r s i m p l e m e n t i n g component

inspectors, maintainerspotential reusers

Modules are collections of programs and data structures that share a secret. Components are collections of programs that are shipped and used as a unit.

This is a classic list but when it was new, we did not know how to do it.


31/61


Document Information Content (Informal)

Document ContentSoftware Requirements

DocumentBlack Box specification, identifies all outputs and inputs and describes relation between output values and input history.

Module Guide Informal description showing the hierarchical decomposition of the system into modules and the secret of each module.

Module Interface Specifications

Black Box specification, identifies all outputs and inputs and describes relation between output values and input history.” Usually shows externally invokable programs.

Module Implementation Design Document

Documents complete data structure, effects of all externally visible programs on data, abstraction function or relation (data interpretation) - design can be verified before coding begins.

Program Uses Structure Description of permitted usage of one access-program by another. Determines the usable subsets of product.

Display Method Program Documentation

Hierarchical decomposition of program into “small programs” with specification of subject program and programs used.


32/61


Example: Functional Definition of Document Content

Deterministic terminating program effect can be described by a function from data-states to data-states. (x,y) in that function if a program started in state x will terminate in state y. Function may be partial.

• Function can be described by precondition/postcondition pair.

• Function can be described by Dijkstra’s “wp” (weakest precondition).

• Function can be described by predicates (Hehner).

• Function can be described by concurrent-assignment (Mills).

• We represent the function using tabular expressions.

More is needed for non-deterministic programs. • relation (data states ⇒ data states)

• competence set (starting states with termination guaranteed)


33/61


Why we need complete requiquirements documents:

A Small Horror Story That is Close to my Heart.Product: A motion sensitive pacemakerSituation: Rarely needed, only if heart rate drops to low for activity level.Software: Measures acceleration, estimates activity level, computes expected heart rate, intervenes (causing discomfort) if rate is lower than expected.Parameters include resting heart rate and slope of curve.Resting heart rate can only be set in multiples of 10.This does not meet patient’s requirements. Software requirements were never documented or reviewed by users.Many patients have to chose between too low and too highThis would not have happened if the planned behaviour had been documented and reviewed by experts.


34/61


Why Programmers Should Not Make User-visible DecisionsContext:

• U.S. attack aircraft with two altimeters; pilot can choose one

• Software checks values, switches altimeters if values unreasonable.

Question:What should we do if both altimeters are broken? • Programmer asks pilot: “What is average altitude of plane inflight?”

• Program displays average altitude when altimeter is broken.

The answer to the real question: Flash Pull-Up cue.The result: Pilots have been trained to watch for “average” altitude appearing for more than a few seconds and told to “pull up” if that happens.

A requirements document should remove user visible decisions from the realm of the programmer.


35/61


A Small Success StoryPROSYS: A small software company in Darmstadt, GermanyDeveloper and customer sit down and complete

• A list of quantities of interest

• A set of tables

They check for completeness and consistency.They initial the tables.The tables are used to develop the software.60% of the code can be generated by simple tools.There is no doubt about who pays for each “fix”.The Secret:! The tables constitute a precise requirements document.


36/61


Requirements Documents: Readers Digest Version: • Produce complete list of all outputs (with possible value information)

• Produce complete list of all inputs (with possible value information)

• Characterize the physically possible histories. (NAT)

• Take outputs one at a time and describe value as a function of history. Make sure you include undesirable events.

• Use tabular format if there are many cases.

• Check against physical world (NAT) for complete coverage.

• Check against physical world for theoretical implementability

• Use as the basis for simulation (NRL tools)

• Find specialists to review in their specialty by asking them to answer questions on the basis of the document.

• Check for completeness and consistency.

• Identify “commonalities” and “variabilities”

• Hand over to Software Architects. Maintain!!!!!


37/61


Documentation For “Programming in the Large”

The following was well understood at least 30 years ago.Make major design decisions (those that affect many modules) before coding.Make decisions explicitly and consciously.Record, review, and keep those decisions up to date.Make them constraints on the programmers.Revise them if exceptions are needed.These “big” decisions are early decisions, the hardest to change.These decisions are often made unconsciously and

• never reviewed,

• never documented, and

• often forgotten by the programmersThe result is software that is hard to understand, test, inspect, and maintain.


38/61


Modules vs. Components

Module (historically): • tasks (work-assignments) for developers (management unit). • should have a shared “secret” that it hides. Only module that has to be

changed if the hidden decision has to be changed.

Component: • distribution unit - use as a whole or do not use it • should offer an integrated set of services

Are they the same? • A module may include several components/

• A component may include (parts of) several modules

• Often something is both a module and a component.

Same documentation scheme for both.


39/61


Designing and Documenting the Module Structure

The most important structure • Constrains all of the others

• Essential before implementation can proceed.

What would make a module structure good? • Parts can be designed independently.

• Parts can be implemented independently.

• There are no duplicate or almost alike pieces of code (clones, cut/pasties)

• Parts can be tested independently.

• Parts can be changed independently.

• Integration is easy if the modules met their specification

• Maintainers can find the relevant code and change it quickly


40/61


Larger SystemsThere are many implementation decisions (hundreds, hard to count).There are many details.The structure is inherently much more complex.This leads to new issues. Among them:

• How can we keep the project under intellectual control?

• How can we maintain conceptual integrity?

• How can we keep the maintenance cost down?

• How do we deal with unstructured lists of modules?

• How can we tell when we have them all?

• How does everyone remember the names?

• How do we avoid duplication?•


41/61


Group Modules Into Classes

Apply the principle of refinement • Eases check for completeness

• Assures lack of duplication (if done properly)

• Eases achievement of consistency.

Leads to more helpful naming conventions.Make a specific module easier to find.


42/61


Documentation of a Module Structure

Module structures are documented in a Module Guide, which states only the secret of each module. • The module guide is hierarchically structured; the structure of the

document mirrors that of the system.

• The top level partitions the system into modules.

• Any module may be partitioned (if secrets can change independently)

• Partitioning introduces no new secrets: refines the old ones.

• There should be no shared secrets.

• Stop partitioning only if a module is easily replaced.

The module guide is the only document to be read by allIn larger systems it may be organized as a set of documents for each major module.


43/61


Per-Module Documents • Precise, complete interface description • Each implementation of a module (there can be several)

requires a module internal design document.All documents must be kept up to date.If it is difficult for designers to identify the “secret” of their module, that the module structure is wrong.The existence of “cross cutting concerns” is a sign of poor design, often based on poor implementation.


44/61


Interfaces

One of the most important, and least well understood, concepts in Software Engineering. Often, confused with syntax of invocations or a shared data structure.Definition: Interface

Given two communicating software components, A and B, B’s interface to A is the weakest assumption about B that would allow you to prove that A is correct.

Any change in B that invalidates its interface to A means that, A could not be proven correct and should be changed.Interfaces determine the difficulty of changing software.


45/61


Surprising Observations about Interfaces. • There isn’t necessarily a 1:1 relation between a program and an interface.

• Interfaces not symmetric. B’s interface to A differs from A’s interface to B.

• B may have an interface to A even if A does not have an interface to B.

• A component may have a specified interface. This tells the developers of other programs what they may assume about the specified component.

• If the developers of a component, A, make use of facts about a specified component, B, that are not implied by B’s specified interface, the actual interface is stronger than the specified interface and A should be considered incorrect (even if it is working).

• B may have an interface with A even if neither invokes the other. For example, the correctness of A may depend on B maintaining a shared data structure with certain properties.

• Published interface (assumption that can be made by all) should imply the actual pair-wise interfaces but sometimes does not (bad error).


46/61


Interface DesignSince interface changes affect more than one module, care is required.The assumptions in an interface should be unlikely to change.Since software designers may not know what will change, the assumptions must be documented and reviewed by the relevant experts.Assumptions about what information will be made available by a component and what information will be needed by a component are less likely to change than assumptions about the representation of such information.Interfaces in the form of get/set programs are less likely to change and the changes are often only additions. Assumptions are often very subtle.Changes are often only predictable by specialists. Because the software developers often don’t know the application details and the people who do don’t understand software, a disciplined systematic design and review procedure is needed.


47/61


Interface Documentation

The most important interfaces are those between modules and between components.If these are information-hiding they must be described using a “black box” method.Much of the internal state representation will be hidden.Trace Function Method analogous to SCR method.Value of each output is shown as function of history of inputs and outputs.


48/61


Extract from Module Interface Document - I

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’)

33/42

David Parnas! ! ! ! ! ! ! ! ! 2008 May 23 16:33 ! ! ! ! TFM slides 2008 slides


49/61


Extract from Module Interface Document - II

Output Functions

hr(T) ≡

PGM(r(T)) = SET HR ∧0 ! !in(r(T)) < 24 "in(r(T))

¬ (0 ! in(r(T)) < 24) hr((p(T)))

PGM(r(T)) = SET MIN hr((p(T)))

PGM(r(T)) = INC ∧min(p(T))= 59 ∧

hr(p(T))= 23 0

¬ hr(p(T))= 23 1+ hr((p(T)))

¬ (min(p(T))=59) hr((p(T)))

PGM(r(T)) = DEC

∧

¬ (min(p(T))= 0) hr((p(T)))

min(p(T))= 0 ∧¬ (hr(p(T)))= 0 hr((p(T)))-1

hr(p(T))= 0 23

T= _ 0

34/42

David Parnas# # # # # # # # # 2008 May 23 16:33 # # # # TFM slides 2008 slides


50/61


The Uses Structure

Parts: programs - not modules or componentsRelation: uses:Definition: Given program, A, with specification S and a program B, A uses B if A cannot satisfy S unless B is present and functioning correctly.

Why is this important? • Determines what subsets will run and can be sold/tested/delivered

Why programs and not modules or components? • Some subsets contain only part of a module or component.


51/61


Designing for Extension and Contraction

• We need program families (a.k.a product lines)

• Different installations require different capabilities.

• For ease of alteration, the uses structure should be a hierarchy.

• Loops mean that the program will be difficult to test.

• Loops mean that there will be fewer subsets.

• Flat structures are a sign that the program is probably larger than it need be.


52/61


Documentation of the Uses Structure • Incidence Matrix

• Graph (picture)

Pictures are good for smaller systems but hard to maintain.Use either one: the information is the same.Tools can be built for

• checking of relation to make sure it is a hierarchy and allows stated subsets.

• generation of subsets. A LEVEL IS NOT A MODULE

These are not “layers of abstraction”.Abstractions are provided by modules; the programs in a module need not be on the same level.Dijkstra’s THE system (1968) placed synchronization below memory allocation.Later (much later) he said it should have been “sandwiched” (not his term).


53/61


Display Form of Program Documentation

Every display has 3 parts.

• A specification of a program

• The program text (short)

• Specifications for all invoked programs


54/61


Sample Display

DEPARTMENT OF COMPUTING AND SOFTWARE • SOFTWARE QUALITY RESEARCH LABORATORY • CONNECTING THEORY WITH PRACTICE

McMaster University 688 June 2002 16:00InspectwithNever.fmDISPLAY 2

Specification

Body external variables: e, V, index, found, low, high (from Display 1)

R2(,) =((‘low ! ‘high) " (‘found = false) " #i [ (‘low ! i < ‘high) $ (‘V[i] ! ‘V[i+1]) ]) $

%i [ (‘low ! i ! ‘high) " (‘V[i] = ‘e) ]=

true false

index’ | ‘V[index’] = ‘e true

found’ = true false

low’ | true true

high’ | true true " NC(e, V)

DEPARTMENT OF COMPUTING AND SOFTWARE • SOFTWARE QUALITY RESEARCH LABORATORY • CONNECTING THEORY WITH PRACTICE

McMaster University 698 June 2002 16:00InspectwithNever.fm

DISPLAY 2 (Continued)

Program (Repeated)

New variable (to be declared in the embedding block):var med : integer;

Program statements:{Body}while not found and (low ! high) do begin

med := (low + high) div 2;Test

end

Specifications of Subprograms

END OF DISPLAY 2

Test external variables: e, V, index, found, low, high, med (on Display 3)

R3(,) = (‘low ! ‘med ! ‘high) "

‘V[‘med]< ‘e = ‘e > ‘e

index’ | true index’ = ‘med true

found’=

‘found true ‘found

low’=

‘med + 1 ‘low ‘low

high’=

‘high ‘high ‘med # 1 $ NC(e, V, med)


55/61


Our Code Inspection Process(1) Prepare a precise specification of what the code should do

(2) Decompose the program into small parts appropriate for the “display approach”

(3) Produce the descriptions required for the “display approach”.

(4) Compare the “top level” display description with the requirements specification.

Observations:• You can’t inspect without precise requirements.

• Step (2) would already have been done if you use the display method for documentation.

• Step (3) is truly an active design review. All reviewer work is reviewable.

• If you did not already have it, the by-product is thorough documentation.

• It’s a bunch of small steps and very systematic.


56/61


Effectiveness of Document Support Inspection

Two Programs in two different languagesTested for six years before inspection - believed correct218 Discrepancies

• 200 neutral or improvements • 18 required repairs

In 15 years of use and modification no further programming errors were found.

Methods continue in use without consultants!Good documents lead to good code.


57/61


The Bottom Lines:

Producing no documentation gets you in trouble.Producing bad documentation might be worse.Producing good documentation: • will help you get the requirements right

• will help you get interfaces right

• will help you in your testing

• will help you in your inspections

• will help you in maintenance and upgrades

• will help you manage a product line effectively.

Define the content of each document (as illustrated)Use appropriate (mathematical) tabular expressions


58/61


Management’s Role in Document Driven Design

Management is getting something done without knowing exactly what it is. (and much more).Management can undermine any effort by either not demanding it, not leaving time for it, or not supporting it.

• Insist that it isn’t done if its not documented it.

• Schedule document reviews

• Insist that software testers test against documents using the documents to generate oracles and test cases.

• Insist on document guided inspections for critical parts.

• Allow no change without document revision.

Without management support it wonʼt work!


59/61


Research Problems

More documents (e.g. sequential process structure)Various forms of composition given these documentsReliability given these documentsMore table typesMore examples (publishable)Tools that are more than Masters theses • input tools

• format tools

• better checking tools

• better simplification tools

• composition (relational) tools


60/61


Thank YouQuestions?Discussion?Shoes?

•


61/61
