Guideline: Requirement Pitfalls |  |
This guideline describes common pitfalls to avoid in defining and writing requirements.
Relationships
Related Elements | Detail Requirements Detail Use Cases and Scenarios Requirements Find and Outline Requirements
Main Description
Research and experience shows that requirements errors are very common, accounting for as much as 56% of all errors made during development [TAV84]. Compounding this problem is the fact that the cost of correcting requirements errors increases exponentially throughout the software development lifecycle [BOE88]. Frederick Brooks summarized this situation nicely: The hardest single part of building a software system is deciding what to build. No other part of the conceptual work is as difficult as establishing the detailed technical requirements…. No other part of the work so cripples the resulting system if done wrong. No other part is as difficult to rectify later.[BRO87] Therefore, it is critical that you detect requirements errors as early as possible, before they propagate to design, implementation, and test artifacts. # What to avoid when writing requirements Although there is sure way to eliminate requirements errors in general, there are common pitfalls in writing requirements that are relatively easy to avoid [TEL06]. ## Ambiguity Avoiding ambiguity is one of the most difficult mandates in writing requirements. Try to write as clearly and explicitly as possible. Be specific. If you must use vague or ambiguous terms, make sure that you define them in the glossary. Have several colleagues and stakeholders review your requirements to ensure a consistent, common understanding. Although there is no definitive test for ambiguity, other than consensus, some dangerous ambiguities can be caused by the use of the words for, or, and unless. Example "The same subsystem shall also be able to generate a visible or audible caution/warning signal for the attention of the co-pilot or navigator." Which subsystem? Is the signal to be visible, audible, or both? Is this both a caution and a warning, just a caution, or just a warning? Is it for both the co-pilot and the navigator or just one of them? If just one of them, which one and under what conditions? ## Multiple requirements Requirements that contain conjunctions (words that join independent clauses together) are dangerous. Problems arise when readers try to figure out which part applies, especially if the different clauses seem to conflict or if the individual parts apply separately. Multiple requirements also make verification more complex. Dangerous conjunctions include: and, or, but. Example "The battery low warning lamp shall light up when the voltage drops below 3.6 Volts, and the current workspace or input data shall be saved." Should the battery low-warning lamp light up when the voltage drops and when the workspace is saved? Should the battery low warning lamp light up and the workspace be saved when the voltage drops? ## Let-out or escape clauses Requirements that include options or exceptions are dangerous. They seem to ask for something definite, but at the last moment, they back down and allow other options. Problems arise when the requirements are to be tested, and someone has to decide what (if anything) could prove that the requirement was met. Dangerous words that imply exceptions include: if, when, but, except, unless, although. Examples "The forward passenger doors shall open automatically when the aircraft has halted, except when the rear ramp is deployed." "The fire alarm shall always be sounded when smoke is detected, unless the alarm is being tested or the engineer has suppressed the alarm." The latter sentence is a truly dangerous requirement! ## Rambling Long, rambling sentences, especially when combined with arcane language or references to unreachable documents, quickly lead to confusion and error. Example "Provided that the designated input signals from the specified devices are received in the correct order where the system is able to differentiate the designators, the output signal shall comply with the required framework of section 3.1.5 to indicate the desired input state." ## Premature design Requirements should specify the design envelope without unnecessary constraints on a specific design. If we supply too much detail, we start to design the system. Going too far is tempting for designers, especially when they come to their favorite bits. Danger signs include names of components, materials, software objects or procedures, and database fields. Example "The antenna shall be capable of receiving FM signals, using a copper core with nylon covering and a waterproof hardened rubber shield." Specifying design rather than actual need increases the cost of systems by placing needless constraints on development and manufacture. Often, knowing why is much better than knowing what. ## Mixing different kinds of requirements The user requirements form a complete model of what users want. They need to be organized coherently to show gaps and overlaps. The same applies to system requirements, which form a complete functional model of the proposed system. A quick road to confusion is to mix up requirements for users, systems, and how the system should be designed, tested, or installed. Danger signs are any references to system, design, testing, or installation. Example "The user shall be able to view the currently selected channel number which shall be displayed in 14pt Swiss type on an LCD panel tested to Federal Regulation Standard 567-89 and mounted with shockproof rubber washers." ## Speculation Requirements are part of a contract between customer and developer. There is no room for wish lists, meaning general terms about things that somebody probably wants. Danger signs include vagueness about which type of user is speaking and generalizations, such as usually, generally, often, normally, typically. Example "Users normally require early indication of intrusion into the system." ## Vague, undefined terms Many words used informally to indicate system quality are too vague for use in requirements. Vague terms include, among others: user-friendly, versatile, flexible, approximately, as possible. Requirements using these terms are unverifiable, because there is no definitive test to show whether the system has the indicated property. Examples "The print dialog shall be versatile and user-friendly." "The OK status indicator lamp shall be illuminated as soon as possible after the system self-check is completed." ## Expressing mere possibilities Suggestions that are not explicitly stated as requirements are invariably ignored by developers. "Possible options" are indicated with terms such as may, might, should, ought, could, perhaps, probably. Example "The reception subsystem probably ought to be powerful enough to receive a signal inside a steel-framed building." ## Wishful thinking Wishful thinking means asking for the impossible. Engineering is a real-world activity, and no system or component is perfect. Wishful-thinking terms include reliable, safe, handle all unexpected failures, please all users, run on all platforms, never fail, upgradeable to all future situations. Examples "The gearbox shall be 100% safe in normal operation." "The network shall handle all unexpected errors without crashing."
This program and the accompanying materials are made available under the Eclipse Public License v1.0 which accompanies this distribution. OpenUP Copyright.