|Karl E. Wiegers, Ph.D.|
Many software requirements suffer from ambiguity. Ambiguity means that a single reader can interpret the requirement in more than one way or that multiple readers come to different interpretations. In either case, ambiguous requirements lead to confusion, wasted effort and rework. This article describes several common types of requirements ambiguity and suggests how to avoid them.
Negative, or inverse, requirements state what the system will not do. Here's an example from an actual project: "All users with three or more accounts should not be migrated." Try to rephrase negative requirements into a positive sense: "The system shall migrate only users having fewer than three accounts." When changing a negative requirement into a positive one, you often need to insert the word "only" to clarify the conditions that permit the system action to take place. Double and triple negatives are especially confusing; avoid them in all situations.
Boundaries between numerical ranges or date ranges are a common source of missing requirements. One requirement might describe what the system does if the amount of the sale is less than $100, while a second requirement describes the behavior if the amount is more than $100. But what happens if it's exactly $100? That's not defined. Similarly, if two requirements are written so that the endpoint of a range appears in both requirements, the expected behavior is ambiguous. Use the words "inclusive" or "exclusive" to make it clear whether the endpoints of the range are included or not.
Synonyms and near synonyms
Use specialized terms consistently throughout the project documentation. A requirements specification is not a place to creatively vary your language in an attempt to keep the reader's interest. If your project involves several terms that have similar but not identical meanings, put those into a glossary so everyone knows where to go for the exact definitions.
Pronouns offer another opportunity for confusion if the antecedent is for each pronoun is not absolutely clear. If you say "this" or "that," there should be no confusion in the reader's mind as to what you are referring to.
Abbreviations i.e. and e.g.
These abbreviations are often misused. The abbreviation i.e. means "that is;" whatever follows is a complete list of items in the stated category. The abbreviation e.g. means "for example," so the items that follow are merely representatives of the complete set. These abbreviations are so often used incorrectly that I don't trust them in requirements. Use English words instead of Latin abbreviations to avoid any confusion.
Adverbs are subjective and qualitative, and they inevitably result in diverse individual interpretations. Here's an illustration from an actual specification: "Generally incurs a 'per unit' cost…" But this requirement did not provide any indication regarding the conditions under which we would not incur a per-unit cost or what to do then. I don't know how to determine whether we've satisfied a requirement that says "Provide a reasonably predictable end user experience." I guess it doesn't have to be completely predictable.
With rare exceptions, such as "input/output," avoid using the A/B writing construct, as in "feature/function." This can be interpreted in many ways. Is a feature the same as a function? Are we referring to features and functions? Features or functions? Features divided by functions? Sometimes this A/B notation means the author isn't really sure exactly what to say so he's leaving it up to all readers to interpret as they wish. This is an invitation to confusion.
It's important for requirements to be precise because our objective is clear and effective communication. Watch out for natural language expressions that can be read in a variety of ways.
About the author: Karl E. Wiegers is Principal Consultant with Process Impact in Portland, Ore. He is also the author of More About Software Requirements: Thorny Issues and Practical Advice, Software Requirements, 2nd Edition; Peer Reviews in Software: A Practical Guide; and Creating a Software Engineering Culture.
This was first published in February 2007