Precise Software Documentation

  • 2010-11-17
  • Research

Part I. Talk by David Lorge Parnas, Professor Emeritus at the McMaster University, Hamilton Canada, and at the University of Limerick, Ireland

The Distributed Systems Group of the Information Systems Institute invites to the following guest lecture:

17. -18. November 2010, 14:00 - 18:00 Uhr

Wednesday, 17. November 2010, EI 10, Gusshausstr. 27-29


Precise Documentation: The Key To Better Software (overview)

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 softwareproduct’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 recentimprovements 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 softwarerequirements 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, EI 3, Gusshausstr. 25 **


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 claimed that, 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.


Dr David Lorge Parnas has been studying industrial software development since 1969. Many of his papers have been found to have lasting value. For example, a paper written 25 years ago, based on a study of avionics software, was recently awarded a SIGSOFT IMPACT award. Parnas has won more than 20 awards for his contributions. In 2007, Parnas was proud to share the IEEE Computer Society’s one-time sixtieth anniversary award with computer pioneer Professor Maurice Wilkes of Cambridge University. Parnas received his B.S., M.S. and Ph.D. in Electrical Engineering from Carnegie Mellon University. and honorary doctorates from the ETH in Zurich (Switzerland), the Catholic University of Louvain (Belgium), and the University of Italian Switzerland (Lugano). He is licensed as a Professional Engineer in Ontario.

Parnas is a Fellow of the Royal Society of Canada (RSC), the Association for Computing Machinery (ACM), the Canadian Academy of Engineering (CAE), the Gesellschaft für Informatik (GI) in Germany and the IEEE. He is a Member of the Royal Irish Academy. Parnas is the author of more than 270 papers and reports. Many have been repeatedly republished and are considered classics. A collection of his papers can be found in: Hoffman, D.M., Weiss, D.M. (eds.), “*/Software Fundamentals: Collected Papers by David L. Parnas/*”, Addison-Wesley, 2001, 664 pgs., ISBN 0-201-70369-6. Dr. Parnas is Professor Emeritus at McMaster University in Hamilton Canada,and at the University of Limerick Ireland and an Honorary Professor at Ji Lin University in China. He is President of Middle Road Software.


  • David Lorge Parnas, Professor Emeritus at the McMaster University, Hamilton Canada, and at the University of Limerick, Ireland

Note: This is one of the thousands of items we imported from the old website. We’re in the process of reviewing each and every one, but if you notice something strange about this particular one, please let us know. — Thanks!