Guest Lecture: David Lorge Parnas
Precise Software Documentation
The Distributed Systems Group of the Information Systems Institute invites to the guest lecture of David Lorge PARNAS: Professor Emeritus at the McMaster University, Hamilton Canada, and at the University of Limerick, Ireland.
Wednesday, 17. November 2010, 14:00 – 18:00 h, EI 10, Gußhausstraße 27‐29, 1040 Wien
Precise Documentation: The Key To Better Software (overview)
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.
From Requirements to Architecture
This paper discusses the importance of requirements documents and presents a method of preparing a requirements document for use by developers, users, and maintainers.
The use of functional methods and tabular expressions for producing precise requirements documentation is explained and illustrated. This includes:
- An explanation of the two-variable model
- Why the two variable method is not practical for software requirements documents.
- A four‐variable model for software requirements documentation
- Structuring the requirements document
- The concepts of mode and mode classes requirements documentation
- How a well‐structured requirements document can be used to maintain clear traceability
between code and requirements.
Thursday, 18. November 2010, 14:00 ‐ 18:00 h, EI 3, Gußhausstraße 25, 1040 Wien
Module Interface Documentation with TFM
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 of 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.
Document driven inspection and testing
Software has a well‐earned terrible reputation. Over the years, many experts have said that they would not trust software for safety‐critical tasks. Others have claimedt hat, at least in practice, it is impossible to get correct software. They have claimed that inspecting and testing cannot be used to find all the errors, only to estimate the number remaining. There is no theoretical basis for such assertions but they seem consistent with empirical observations. This lecture discusses quality assurance procedures that were developed, and proven effective, in the approval process of safety‐critical software for a nuclear power plant in Ontario, Canada. Their novel feature is their use of highly structured, precise (mathematical) design documentation.