Lecture 18: Requirements Specifications / Passing the Word
Today's Lecture
- Brooks, Chapter 6: Passing The Word
- Requirements Specifications
Brooks’ Corner: Passing the Word
- This chapter is about communicating design decisions and the various mechanisms you can employ.
- Brooks begins by looking at written specifications (or, as he calls them, the manual). And covers several key points:
- The architects (designers) write the manual, implementers (developers) DON'T.
- The manual needs to be updated regularly, with each new version clearly marked.
- The manual describes everything that a user “sees” about a system, all of its external behavior
- It must also refrain from describing what the user does not see, because that is implementation and that's the developer's chance to be creative.
- Finally, its style must be
precise, full, and accurately detailed.
- Brooks holds up as an example of good specification writing, the System/360's own manual, the Principles of Operation and in particular the appendix written by Gerry Blaauw that outlines the limits of System/360's compatibility with previous IBM operating systems.
Formal Definitions
- Brooks then moves on to the topic of formal definitions.
- A formal definition or specification is one that is somehow based on mathematics and/or formal logic
- Formal specifications are good in that they are much more precise than natural language text, but…
- what they lack is comprehensibility!
- Formal specs are difficult to understand and you often need training just to be able to read and write them.
- With natural language text,
one can show [structure and delineate it in stages], and give examples. One can readily mark exceptions and emphasize contrasts. Most important, one can explain why.
Solution: Use Both at Once
- Given the previous discussion, Brooks predicts that software development practice will evolve to include both formal specifications AND prose descriptions.
- He maintains that it must be clear which version of the specification is primary. That specification is the one responsible for answering developer's questions. The secondary specification is then used to supplement and/or clarify the primary spec.
Specifying Semantics
- Specifying a system's syntax with formal specifications is often straightforward. The hard part is specifying a system's behavior.
- Since the formal specification uses mathematics, if you attempt to use it to specify behavior it will feel very much as if you are implementing that behavior.
- In those situations, you need to be very careful, because you need to specify only the user-visible, or external, behavior of the operation, and stay away from specifying the internal implementation of the operation.
- Brooks mentions that when vendors first started to create computers that needed to be compatible with previous generations, the previous machine would act as a specification. This was good because if you ever had a question about the “spec”, you simply turned on the previous computer, posed it a question and observed its behavior. Its behavior was the “answer” to your question.
- The problem with this approach is that using a concrete implementation of a system over-prescribes the requirements and certain side-effects of behaviors on the previous system may become part of the spec for the new system, even though the old side-effects may never have been intended for public use or may slow the new system down by it having to emulate all of these old behaviors.
Other techniques
- Brooks also talks about other ways in which design decisions were conveyed to all members of the development team
- weekly and annual problem meetings
- “telephone log” of the architects (today, we might use development blogs)
- In addition, he mentions two techniques for keeping the development team “honest” with respect to the specification.
- Encourage multiple implementations of the same specification. This approach encourages the team to work really hard to get the specification right... if a disagreement arises about a particular interpretation of the spec, with two implementations going one way and a third going another, it will be easier to clarify the spec and change the third implementation than it would be to require the other two implementations to change to match the third.
- Product Test by an independent testing organization. This organization (now called QA) needs to be a surrogate customer, trained in finding flaws before the system is released to the ACTUAL customer.
Requirements Specifications
- Why do we need them?
- A specification is a clear statement of intent
- Clear intentions are more easily translated into “sharp” milestones (Brooks, pg. 154-155) that are easy to track and evaluate
- A specification should be as specific and detailed as possible
- A specification is a contract between a customer and a supplier
- desktop software: can sometimes suffer from not having a clear contract specified before the software is developed
Specifications: The Good, the Bad, and the Ugly
- Specifications cover many topics
- The Good
- specified conditions of correct operation
- When the user closes a document window, the associated data file is saved and closed
- The Bad
- specified error conditions
- If the file system reports an error during a save operation, the file’s associated document window is not closed and the user is notified of the error
- The Ugly
- unspecified conditions (!!)
Specifying Input
- Users are unpredictable!
- Do not specify input that a program may receive
- Instead, specify a function from input to output
- Example:
- Upon input of an integer from 1 to 100 inclusive, the program will determine if its input is prime and report its results to the user
- Any input other than an integer from 1 to 100 inclusive, including integers outside the range of 1 to 100, non- whole numbers, and non-numeric input will result in an error message
- Discussion
- The example is very specific
- It defines its legal inputs carefully and specifies illegal inputs explicitly
- It defines “what” the program should do, not “how” the program should do it
- Given these requirements you can create several alternative designs that satisfy them
- For instance, a system that uses speech input and output is perfectly acceptable, as is a system with a graphical user interface or a command line interface
Specifying “What” not “How”
- A requirements specification specifies the behavior of an application (what Brooks referred to as its “externals”), not its implementation
- Specifying Implementation
- The program must have a linked list to hold pending alarms. Each alarm in the list is a structure containing the date, hour, and minute the alarm should sound. The list should be sorted according to time.
- Specifying requirements
- The program shall provide an alarm clock feature. A user can specify multiple alarms. Each alarm rings the computer’s bell when it is activated.
More on specifying behavior
- A requirements specification is the first document created for a program
- Specifying a program’s behavior allows for maximum flexibility during design and implementation
- It answers the question: “Why am I writing this program?”
- Specifying implementation first, on the other hand discourages the consideration of alternatives. It constrains the design inappropriately
Formal and Informal Specs.
- Specifications can be informal
- natural language based
- no matter how hard you try, natural language specifications will always have some degree of ambiguity
- or formal
- based on a mathematical model
- typically requires training to use and apply correctly
Example Informal Specification
- The meaning of integer division, div(a, b), is the same as floating point division with the fractional part rounded off towards zero.
- The meaning of modulo, mod(a, b), is the value of the fractional part that would be rounded off by div(a, b).
Example Formal Specification
- div(a, b) = integer q, such that
- 0 ≤ (a - b * q) < |b| if a > 0
- 0 ≥ (a -b * q) > -|b| if a < 0
- 0 if a = 0
- mod(a, b) = a - (div(a,b) * b)
More on Formal Specifications
- Being based on a mathematical model means
- every symbol is well defined
- syntax: how is a symbol combined with other symbols
- semantics: what is the symbol’s meaning, how does it behave
- Formal specs often reuse information
- In our previous slide, we did not define the greater than, less than, and equals symbols;
Trade-offs between formal and informal specs
- Formal specs are not always better than informal ones
- In early stages of a development project, you may not know or understand enough to create a formal spec
- an informal spec can serve as a starting point
- Formal specs are often difficult to understand
- This can discourage people from using them
- An informal spec can be used to annotate and explain a formal spec
- Formal specs are typically expensive to create
- They require specially trained workers
- Not all parts of a project need to be formally specified: use formal specs where its absolutely critical that a program behaves as specified; such as flight control software
Coming Up Next
- Lecture 19: Functional Testing
- Quiz 7: Available after this lecture. Don't forget to take it!!!
- Homework 7 Assigned
