The good requirement
In short: A good requirement is necessary, unambiguous, complete, singular, feasible, verifiable and correct. A set of requirements must also not contradict itself. A bad requirement is a defect you can catch by reading, before any code exists.
Problem
"The discount is shown clearly"
The requirement is one sentence: "The discount is shown clearly in the cart." The designer puts it in grey text under the total. The tester sees it: shown, readable, passed. The owner sees it at the launch and asks where the red struck-through line he wanted is.
Everyone read "clearly" their own way. Nobody got anything wrong, and the product is still not what it should be.
The defect is in the sentence. It can be caught by reading, before anyone has drawn or written anything.
The idea
What makes a requirement good
The standard ISO/IEC/IEEE 29148 lists the characteristics of a good requirement. Here they are with the shop:
| Characteristic | Means | Example of a violation |
|---|---|---|
| Necessary | remove it and something important is missing | "The logo is in the top left corner", written as a requirement nobody asked for. |
| Appropriate | the level of detail fits; it does not say how when it should say what | "The order is written to a table with three columns" at the level of "what accounting needs". |
| Unambiguous | it can be read only one way | "The code is valid once": per customer or per order? |
| Complete | nothing more is needed to understand and check it | "Returns within 14 days": from when? |
| Singular | it says one thing | "Shows the total and allows changing the address." |
| Feasible | it can be built with the time, money and technology there is | real-time stock from suppliers with no connection |
| Verifiable | there is a way to show that it is met | "The cart opens quickly." |
| Correct | it states exactly the need | "Over 50 €" when the owner wants "from 50 €". |
| Conforming | it follows the format the team agreed on | every requirement is "R-number, sentence, measure", and this one is a paragraph with no number. |
Do not learn the table by heart. The important questions are three: can it be read only one way, can it be checked, and is it the need.
More precisely, if you are curious
The nine characteristics above are from the second edition of ISO/IEC/IEEE 29148 (2018), for an individual requirement: necessary, appropriate, unambiguous, complete, singular, feasible, verifiable, correct, conforming.
The list has changed between editions and between sources. Older texts also list "traceable" and "implementation-free". Traceability has its own module here, and "implementation-free" is part of "appropriate": a solution is a mistake when it sits at a level that needs a need.
IREB CPRE has its own list of characteristics, close but not with the same names. If you are preparing for an exam, learn the list from the syllabus you are sitting. The idea in both is the same: the requirement must be read one way, must be checkable, and must state the real need.
Try it
Which characteristic is missing?
The idea
Trap words
Some words almost always mean a defect. When you see them, stop:
- "fast", "convenient", "easy", "clear", "modern": no measure. Everyone reads them their own way, and no test can fail. This is unverifiable.
- "etc.", "and others", "as needed": the list is open. The developer will add one thing, the tester another. This is incomplete.
- "if possible", "where feasible", "as appropriate": a loophole. A requirement that may go unmet without being broken is not a requirement. This is unverifiable too.
- "once", "over", "within 14 days": words that can be read two ways. This is ambiguous.
- "the user", "the system allows": who exactly? A customer, an employee, any visitor? This is a requirement with no actor.
- "button", "table", "in the browser" in a requirement for a need: a solution instead of a need.
- And when two requirements say different things about the same case, they contradict each other.
These six kinds are the same ones you will pick in the tasks below.
The idea
How to fix it
The fix is not a nicer word. It is a measure, a condition and an actor. A solution requirement usually has these parts:
[when] [who] [must] [do what] [with what] [how well]
"The cart opens quickly" becomes:
"When the customer opens the cart, the page is shown in under 2 seconds in 95 % of cases, with 500 customers at once, on a mobile network."
"The code is valid once" becomes:
"A customer can use each promo code in one paid order. A second attempt with the same code is refused with the message "The code has already been used"."
The sentences got longer, and that is the price. But now everyone reads them one way, and the tester knows what to check. The strongest check is an example: "Maria pays with AUTUMN10 today and again tomorrow. What happens?"
More precisely, if you are curious
IREB CPRE recommends sentence templates for requirements. One of the best known in practice is EARS (Easy Approach to Requirements Syntax): "When [event], the [system] shall [response]", "While [state], …", "If [unwanted event], then …". In English specifications shall means mandatory, should recommended, may optional.
29148 also gives a list of words and constructions to avoid, for example: superlatives ("the best"), subjective words ("convenient"), vague pronouns ("it"), loopholes ("if possible", "as applicable"), totality words that cannot be checked ("all", "always", "never"), and negative statements where you could say what is required.
Try it
Review: the cart
Mark the words that make the requirement bad, and pick what kind of problem each one is.
Press the words that are a problem; press again to unmark. The arrow keys move from word to word.
The problems in the text
- “quickly” unverifiable: How quickly, on which device, with how many customers? Without a number there is no test that can fail. Better: "95 % of cart loads take under 2 seconds with 500 customers at once".
- “convenient” unverifiable: Convenient for whom, and how is it measured? It can become "a new customer pays without help in under 2 minutes", or link to a specific accessibility requirement.
- “etc.” incomplete: What else? The promo code, the points, the delivery date? The developer will add one thing, the tester another. The list has to be closed.
Three fixes: a number for the time ("under 2 seconds with 500 customers"), a measure for convenience ("a new customer pays without help in under 2 minutes") and a closed list: the total, the delivery, the discount and the points, and nothing else.
The idea
The set of requirements
Every requirement can be good on its own and the set can still be bad. 29148 also lists the characteristics of the whole set:
- complete: it has everything needed. If returns, cancellation or the warehouse are missing, the set is incomplete, however good each sentence is;
- consistent: no two requirements say different things about the same case;
- feasible: all of it together can be built with the time and money there is;
- comprehensible: it is clear what is expected of the system as a whole;
- able to be validated: you can show that the set will meet the needs of the business.
Contradictions are sneaky, because each of the two requirements looks good. "Free delivery over 50 €" on page 3 and "no charge from 50 € inclusive" on page 17 each pass any review on their own. You catch them when you look for them on the same case: exactly 50.00 €.
Exercise
Review the requirements
1. Promo codes. The promo code requirements, as they came out of the meeting.
Mark every place that makes the requirement bad.
Press the words that are a problem; press again to unmark. The arrow keys move from word to word.
The problems in the text
- “The user” no actor: Which user: any visitor, a registered customer, a shop employee? That decides who may use the code and who may not.
- “etc.” incomplete: Only promo codes, or vouchers and loyalty points too? An open list cannot be checked to the end.
- “once” ambiguous: Once per customer or once per order? The two readings give different answers when the customer orders a second time with the code. We have already seen exactly this mistake.
- “If possible,” unverifiable: A loophole: if the discount is not shown, you can always say "it was not possible". Either the requirement is wanted or it is not.
Fixed: "A registered customer can use a promo code in one paid order. The discount is shown in the cart as a separate line with the amount." Vouchers and points get their own requirements.
2. Delivery. Four requirements from the delivery specification, from different pages.
Mark the problems and pick the kind of each. Watch for requirements that contradict each other.
Press the words that are a problem; press again to unmark. The arrow keys move from word to word.
The problems in the text
- “over 50 €” contradicts: R-27 says "from 50 € inclusive". For a cart of exactly 50.00 € the two requirements give a different price. The owner said "from 50 €", so R-12 is the one to fix.
- “If possible,” unverifiable: A loophole: a requirement like this can never fail a test. Either delivery is calculated automatically, or the requirement says when it is not.
- “in the customer's browser” solution instead of need: Where the price is calculated is a decision for the team. The need is "the customer sees the delivery cost before paying".
- “from 50 € inclusive” contradicts: It contradicts R-12 at exactly 50.00 €. The set cannot keep both: one is fixed, and the other can go as a duplicate.
R-12 and R-27 become one: "Delivery is 0.00 € for orders from 50.00 € inclusive, otherwise it is 4.90 €." R-13 loses "if possible". R-14 becomes "The customer sees the delivery cost in the cart before paying", and where it is calculated is up to the team.
3. Returns. The requirements for returning a product.
Mark every place that makes the requirement bad.
Press the words that are a problem; press again to unmark. The arrow keys move from word to word.
The problems in the text
- “within 14 days” ambiguous: From when: the order, the payment or receiving the goods? EU law counts from receiving the goods, and the requirement has to say so.
- “quickly” unverifiable: In how many days? EU law gives the trader at most 14 days after the customer has said they withdraw. The shop may promise less, but with a number.
- “easy for everyone” unverifiable: How is "easy" measured, and who is "everyone"? It can become a concrete requirement: for example, a customer with a screen reader returns a product on their own.
Fixed: "The customer can request a return within 14 days of receiving the parcel. The shop refunds the money within 14 days of the request." And "easy for everyone" is replaced by concrete accessibility requirements that can be checked.
Test