Design through documentation: the path to software quality

does not mean imprecise or vague! • We need precise documentation. Abstract does not mean “wrong”. • An unbounded buffer is not an abstraction, it is a lie. Abstract means that, in a particular document, we omit certain details. • The details that are ignored must be documented elsewhere. • The details that are ignored must be irrelevant for some purpose. Unless we have precise abstract documentation, we will not understand our software. It will be inscrutable. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 8 /48 designdocs.slides. fm 24 February 2003 17:00 A Simple Example: String Copy in Unix-like Systems. Security vulnerability often results from exploitation of unexpected behaviour in routines that copy strings. Do you: • know what your string copy routine does if the string to be copied is longer/shorter than it should be? • know what your string copy routine does if the source string is longer than the destination location? You need to know those things to avoid vulnerability. Do you • know if a successful copy is performed from left to right or right to left? • know the order in which preconditions are checked? You do not need to know those things to avoid vulnerability. Documentation must be precise about the things that we need to know and abstract from the things that are irrelevant for the reader’s purpose. The documentation should be easier to read than the code. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 9 /48 designdocs.slides. fm 24 February 2003 17:00 Why Don’t People Apply Engineering Discipline to Software? 1. Some don’t do not understand the meaning of “engineering discipline”. 2. Some don’t think it’s necessary because the market doesn’t demand it. 3. Some don’t know how to do it. In this talk I want to focus on how to do it but we must also understand the importance of doing it. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 10 /48 designdocs.slides. fm 24 February 2003 17:00 Is Documentation Relevant? “We have better things to do than document” “We sell code, not design documents. ” But, • We cannot collect, review, or check requirements for completeness unless we document them. • We can’t make, review, or live up to structural decisions unless they are documented. • We can’t inspect designs, without design documentation. • We can best inspect programs with the help of program documentation. • Some maintenance programmers estimate that 80% of their time is spent seeking information in documents and verifying its accuracy. Design through documentation is key to better software. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 11 /48 designdocs.slides. fm 24 February 2003 17:00 Two Aspects of Better Software: (1) Better design (2) Better documentation Two Aspects of Better Documentation (1) Better design (easier to document) (2) Using mathematics, which is • more compact, • less ambiguous, • more useful (mechanically interpretable) than natural language. Two Aspects of Better Design (1) Following good software design principles (2) Raising consciousness: documenting design and making decisions more explicit and reviewable. In other words, design and documentation are irrevocably linked. They help (or hurt) each other. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 12 /48 designdocs.slides. fm 24 February 2003 17:00 The Documents that Software Dependant Organisations Need 1. A Requirements Document that tells the users exactly what they will get and tells the programmers exactly what to build. • The challenge is to use one document that is useful to both groups. 2. A Module-guide that guides reviewers and maintenance-programmers to exactly the programs that will be affected by a proposed change. • For all who work on the project, it is restricted in the designs to which it applies 3. A set of Module Interface Specifications that tell programmers what they must build and other programmers, what they can expect of a module. • This is the only information read by both those who build the module and those who use it. 4. A set of Module Internal Design Documents that (1) record major internal design decisions for reviewers, (2) guide the programmers in their coding, (3) help maintainers to understand the code. • This information is only for developers/maintainers of the module in question. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 13 /48 designdocs.slides. fm 24 February 2003 17:00 So why don’t we do it? The fundamental answer, “We do not know how”. Imagine trying to develop an automobile if you do not know how to specify the thread on nuts and bolts. Imagine trying to develop electronic devices and systems if we do not know how to specify impedance, voltage, current, inductance, frequency response. Imagine trying to produce for the petroleum industry if you do not know how to specify viscosity, octane level, etc. Imagine trying to design electronic circuits without a knowledge of circuit theory. You do not have to imagine trying to produce software systems without knowing how to specify component properties. We do it every day. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 14 /48 designdocs.slides. fm 24 February 2003 17:00 Never Build on Sand Software is among the most complex of products. We cannot hope to keep such products under intellectual control, unless we build on a solid, sound, well understood foundation. If • we don’t know the meaning of our notation, or • we don’t know the associated rules of inference, or if • those rules are complex and conditional, using that notation will not help us to understand what we are doing. To build complex products all design notations must have a sound and simple mathematical basis. Today, many people promote Undefined Modelling Languages (UMLs) as a solution. Without a precise definition of their meaning, UMLs become part of the problem, not the solution. Retrofit of definitions, never works. Once people start using vaguely defined notations, the definitions proliferate like weeds. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 15 /48 designdocs.slides. fm 24 February 2003 17:00 Divide and Conquer for Requirements Documentation Consider the controlled variables one at a time. • Describe each one as a function of monitored variables. • Both monitored and controlled variables may be added during this process. Identify modes of operation. • Describe transitions to define modes (using monitored variables) • Define conditions within each mode For each of the identified controlled variables: 1. Prepare an empty table with rows for each mode and columns for each condition. 2. Complete the table with expressions using only monitored variables. 3. Monitored and controlled variables will be added during the design process. • the process reveals forgotten variables • internal variables may be monitored and displayed for diagnostics. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 16 /48 designdocs.slides. fm 24 February 2003 17:00 Bringing Time into the Picture All of these variables can vary with time. For each scalar variable, x, denote the time-function describing its value by “xt”. The value of x at time t is denoted “xt (t)”. The vector of time-functions (v1, v t 2, ., vn) will be denoted by “vt”. Contrary to the statements by some computer scientists, there is no problem dealing with “real” time. No new mathematics is needed. For many systems, the time functions may be replaced by functions of event sequences. • SOFTWARE QUALITY RESEARCH LABORATORY • University of Limerick 17 /48 designdocs.slides. fm 24 February 2003 17:00 Mathematical Definition of Document