{"id":3433,"date":"2013-08-09T08:10:00","date_gmt":"2013-08-09T15:10:00","guid":{"rendered":"https:\/\/www.jamasoftware.com\/?p=3433"},"modified":"2023-01-12T16:56:45","modified_gmt":"2023-01-13T00:56:45","slug":"elements-of-requirements-style-part-3","status":"publish","type":"post","link":"https:\/\/www.jamasoftware.com\/legacy\/blog\/2013\/08\/09\/elements-of-requirements-style-part-3\/","title":{"rendered":"Elements of Requirements Style, Part 3"},"content":{"rendered":"
One of the most common types of requirements problem is missing information. Either entire requirements could be absent\u2014which are hard to spot, being invisible\u2014or individual requirements are missing information that help make them fully comprehensible. In this article I\u2019ll present some examples of both kinds of problems, along with some recommended solutions.<\/p>\n
Omissions<\/h2>\n
When requirements lack important bits of information, it\u2019s hard for all readers to interpret them in the same way unless they make precisely the same assumptions. For instance, a functional requirement might describe a behavior without identifying the triggering cause that leads to that behavior:<\/p>\n
The system shall generate an error report and forward it to the user.<\/p>\n
This requirement doesn\u2019t identify the stimulus that leads the system to produce the error report. Another common mistake involves missing descriptions of how possible exceptions should be handled. In the previous example, what should happen if no errors occur during the processing being described? It\u2019s unspecified, thereby leaving it up to the developer to decide what to do. Options include:<\/p>\n
\n
Do nothing (an assumed default perhaps).<\/li>\n
Present a \u201cCongratulations! No errors found.\u201d message but do not generate a report.<\/li>\n
Generate an empty report and forward it to the user.<\/li>\n
Generate a report stating that no errors were found and forward it to the user.<\/li>\n<\/ul>\n
Perhaps we add the following requirement to address the case in which no errors are encountered:<\/p>\n
If parsing is successful, the system shall not generate an error report.<\/p>\n
This is another description of the system doing nothing, though, as I discussed under \u201cNegative Requirements\u201d in a earlier article in this series. It would be better to state what the system will<\/i> do if no error is encountered, even if it is to simply continue the processing.<\/p>\n
Another kind of incompleteness occurs when requirements describe system behaviors that involve some type of symmetry. Suppose you\u2019re specifying the functional requirements for a bookmark feature in a Web browser. You might say:<\/p>\n
The system shall display the user\u2019s defined bookmarks in a collapsible hierarchical tree structure.<\/p>\n
So, the user can collapse the bookmark tree, but what if he wants to expand it again? It\u2019s easy to overlook that sort of symmetrical or reverse operation. To remedy this, either you could add a second requirement stating that the tree can be expanded, or you could alter this requirement to say \u201c\u2026in a collapsible and expandable<\/b> hierarchical tree structure.\u201d<\/p>\n
If you omit the reverse operation, the customer and the BA might assume that the missing portion of the symmetrical requirement is implied. If you request an undo capability, of course you want a redo capability as well, right? But implicit requirements make me nervous. They involve too many assumptions about the knowledge and thought processes that other stakeholders must have to ensure that we all get what we expect in the final product. I know of a organization that developed its own tool for editing and storing source code in a database, with no written requirements. Unfortunately, they forgot to include the ability to print the contents of the database. The team members no doubt assumed that a printing function would be included so didn\u2019t even think to mention it. They didn\u2019t mention it, and they didn\u2019t get it.<\/p>\n
Boundaries<\/h2>\n
Boundary values in numerical ranges provide additional opportunities for creating ambiguity, as well as being places to look for missing requirements. Suppose you\u2019re writing software for a point-of-sale system and you need to comply with a business rule that states, \u201cOnly supervisors may issue cash refunds greater than $50.\u201d An analyst might derive several functional requirements from that business rule, such as the following:<\/p>\n
\n
If the amount of the cash refund is less than $50, the system shall open the cash register drawer.<\/li>\n
If the amount of the cash refund is more than $50 and the user is a supervisor, the system shall open the cash register drawer. If the user is not a supervisor, the system shall display a message: \u201cCall a supervisor for this transaction.\u201d<\/li>\n<\/ol>\n
But what if the amount of the cash refund is exactly $50? Is this a third, unspecified case? Or is it one of the two cases already described? If so, which one? Such ambiguity forces the developer either to make his best guess or to track down someone who can answer the question definitively. This is an example of the BA generating an inconsistency between a higher-level piece of information\u2014the business rule\u2014and the functional requirements derived from it.<\/p>\n
You can resolve boundary ambiguities in one of two ways. The previous requirement #1 could be rewritten as, \u201cIf the amount of the cash refund is less than or equal to<\/i> $50, the system shall open the cash register drawer.\u201d This preserves the original intent of the business rule and eliminates the ambiguity.<\/p>\n
Alternatively, you could use the words inclusive<\/i> and exclusive<\/i> to explicitly indicate whether the endpoints of a numerical range are considered to lie within the range or outside the range. To illustrate with a different example, you might say, \u201cThe system shall calculate a 20% discount on orders of 6 to 10 units, inclusive.\u201d This wording makes it perfectly clear that both endpoints of the range, 6 and 10, lie within the range subject to the 20-percent price discount. You still need to review a set of similar requirements to make sure the range endpoints don\u2019t overlap, though. For example, note the inconsistency between the following two requirements:<\/p>\n\n
The system shall calculate a 20% discount on orders of 6 to 10 units, inclusive.<\/li>\n
The system shall calculate a 30% discount on orders of 10 to 20 units, inclusive.<\/li>\n<\/ol>\n
The boundary value of 10 is incorrectly included in both ranges. Using a table to show this sort of information is more concise and makes these kinds of errors more evident:<\/p>\n