Properties of Good Requirements Chapter 8

Understandable by end users  End-users are not often software engineers.  Terminology used must agree with end-user’s understanding (for instance, standard accounting terminology.)  End-users understanding must agree with ours. Everyone must understand the same thing!  To ensure predictable operations, the system shall not employ nondeterministic methods The system shall not employ nondeterministic methods  Derived requirement – understood by the implementor System operation shall be predictable and repeatable  Primary requirement – understood by the end user

Non-prescriptive  Non-presecriptive means that the requirement must stipulate what must be done, but not how it must be done.  Requirements are “what”, and the design activity is “how”  Data structures and algorithms belong in the design documents, not the requirements!  The software shall employ B-trees for storage of information kept in memory This is a how, not a what

Correct  Obviously, the behavior specified must be the proper behavior.  Correct implies “completely correct”. For instance, the requirement must indicate the fullest possible conditions. While a requirement to support “at least 3” terminals can be considered correct, if the user expects to eventually expand to 300, the requirement should reflect it! “will support 3 terminals initially, but may expand to 300 over time”

Complete  Complete is a quality that can apply to both the individual requirement and the sum of the requirements.  The requirements set should be considered complete only if it is not missing any requirements that would separate an acceptable system from one that isn’t acceptable!  The system shall provide the operator with the information needed to safely shut down the controlled machinery when an exception occurs. “blanket” requirement, not good  The system shall provide the operator with time-stamped messages describing system exceptions. More complete  The system shall provide the operator with time-stamped messages describing system exceptions (list of exceptions TBD). The messages shall not lag more than TBD seconds behind the exceptions they describe. Best to use TBD if information is not known at time.

Concise (succinct)  Run-on requirements (and prose) can confuse the requirement reader.  Requirements should consist of only the necessary information!  William of Occam, the philosopher, said that argument should be made “without unnecessary ornament”, and that applies to requirements as well.  We feel that good systems provide the end user with good value. Because of this, we think that the system should provide adequate performance with a 3 GB disk, since this is the least expensive disk …  The system shall fulfill all specified functions when configured with a 2-gigabygte disk.

Precise  The bounds of the requirement should be evident and unambiguous. In the case of numerical bounds, it ought to be evident whether the end- points are included or not.  A great contributor to precise requirements is consistency in the means used to represent bounds. Words such as “inclusively” and “exclusively” should be used with care so they are consistent.  The system shall accept valid employee ID numbers from 1 to Are all numbers between 1 and 9999 valid? Is 2 OK as well as 0002?  The system shall accept only valid ID numbers as defined elsewhere. No otherwise valid number will be accepted unless it is an integer between 1 and 9999 inclusive, represented without leading zeros.

Clear  This is the stumbling block for some mathematical specification methods because end-users are not always mathematically adept.  However, even natural language specifications can be unclear if they use words with a ‘high level’ of abstraction.  The items in tab-separated columns and underscore-separated rows of the output may refer to each other, but no item in (row,column) position (i, j) may refer to another in position (p, q) unless p < i, or if i = p, q < j.  The output consists of rows and columns. Items across each row are separated by tabs. There is an underscore between rows. When item X refers to item Y, Y must either be in a row above X, or if they are in the same row, Y must be in a column to the left of X. Any item may not refer to itself.

Unambiguous  Ambiguity is perhaps one of the greatest problems. To parody an old saying: “one word is sometimes worth a thousand pictures.”  The “unspecified referent” is a great problem: when using words like “the”, “it”, “that”, readers can become confused about which “it” the writer is referring to!

Consistent  Requirements should agree with each other: one requirement should not stipulate something that is in conflict with other requirements.  In addition, writing requirements in the same ‘form’ provides the reader with a consistent appearance and (hopefully) understanding.  The system shall track detected airborne objects traveling at speeds from 200 to 400 miles per hour inclusive.  The system shall flag all detected airborne objects traveling at speeds from 300 to 500 miles per hour inclusive.

Traceable  Ultimately code ought to be traceable to the requirement(s) that the code supports. We ought to be able to answer the question “why is this code here?” by tracing the code back through the design to a set of requirements.  We ought to also be able to find the code that supports a requirement quickly, if the requirement should change late in the development cycle.  Support for traceability starts during requirements specification. Each requirement should have a unique identifier.

Modifiable  It’s a reality that requirements can change (sometimes frequently.)  The form used to write requirements should support easy modification of the requirement.  Avoid using “magic numbers” in the requirements. Instead specify “symbolic” values, and define the values elsewhere, very much like manifest constants in code (“ #define ” in C, for instance.)

Testable (verifiable)  Requirements ought to be something that can be verified. In short, they ought to provide outputs that are measurable based on a given set of inputs.  Sometimes, the testing process might impose requirements on the system that must be considered part of the requirments! This is called “design for testability”.

Feasible  “When the start button is pressed, the system shall transmute an ounce of lead into a ton of gold”: This is a clear, unambiguous, testable, modifiable, and even correct requirement, but it is not feasible.  Feasible means that the requirement has a sound basis for design. That is, we probably know at least one way to accomplish this. (If we aren’t sure, we have should be given an opportunity to prototype a solution to find out.)

Summary: how to write requirements?  Requirements describe what outputs we should expect given a set of inputs.  Our requirements could have a form that allows exactly that: If some set of values appear at the inputs Then some set of values appear at the outputs.  For instance: If the student id number is negative Then an error message is printed at the console: “Student ID is out of bounds”