A requirement that leaves its reader to decide
requirement-smellon by default (info)Japanese / English
"As far as possible", "if necessary", "etc." or "and/or" in a requirement
Example
How to fix
Rewrite it so that meeting it can be checked: "as fast as possible" becomes "within 3 seconds", "logs, etc." becomes the full list, and "A and/or B" becomes "A, B, or both".
Why it matters
A requirement in a specification or a contract must be one that any reader can check the same way. "As far as possible" and "if necessary" leave open how much is enough. "Etc." in a requirement leaves open what else it covers, and "and/or" leaves open whether both are meant or one is enough. Studies of requirements (Femmer et al. 2017; Berry et al. 2003) and ISO/IEC/IEEE 29148 all list these among the phrases to avoid. Only a sentence that states a requirement (with shall, must or is required to) is checked.
What it does not flag
Sentences that state no requirement (background, explanation), statutes, and blogs and business documents are not checked. Phrases not on chaff's lists are not reported. In Japanese, an open word in the clause that describes what the requirement is about (SNSなどを通じて…行う取引は、…必要があります) is not reported, since it is not in what the reader is asked to do. An open-ended word inside a name the document defines (a quoted term, one defined in the brackets after it, or one an item of a definition list holds alone and the next paragraph defines) is not reported. "As soon as possible" followed in the same sentence by a limit in numbers ("but in any event no later than two days after") is bounded, and not reported. In a contract, "including, but not limited to" is a term of art that keeps the listed examples from narrowing the class, and is not reported. In Japanese, 等 right before the words that name the kind it gives examples of (印刷等、二次的に利用, "secondary use, such as printing") is not reported either. Nor is a Japanese 等 in a condition (訂正等を行った際に), a right the writer grants (できるものとする) or a prohibition or disclaimer (てはならない, ないものとする), because such a list is kept wide on purpose, or an open list in brackets right after a condition word (場合（…等）, "in cases (…, etc.)"), which gives examples of when the requirement applies.
Turning it off or relaxing it
Technical details
- Layer
- L2
- Status
- stable
- Severity
- info
- Languages
- Japanese and English
- Suited to
- technical/spec, legal, docs, academic, literature, speech
Levels
Set a level for this rule under rules in chaff.yaml. With nothing set, it runs at the level its genre gives it (see By genre below).
| strict | warning |
|---|---|
| normal | info |
| relaxed | info |
This rule has no limit to count to. A level sets how a finding is marked: relaxed keeps the finding and marks it a step lower.
By genre
- Runs by default in
- technical/spec, legal/contract, docs/manual, docs/faq
- Turned off by the genre in
- legal/statute, legal/judgment, legal/patent, docs/glossary, academic/paper, literature/fiction, literature/essay, literature/poetry, literature/play, speech/address, speech/transcript
- Not suited to, and not run in
- technical/readme, blog/tech, blog/essay, blog/owned-media, business/proposal, business/report, business/email, business/press-release, business/meeting-notes
Message
"{matched}" leaves the requirement open
"{matched}" does not say how much is enough to meet the requirement
"{matched}" in a requirement does not say what else it covers
"{matched}" does not say whether both are meant or either is enough
Sources
This page is built from the rule's definition file:packages/chaff/rules/requirement-smell.yaml