Граматика для написання технічних вимог

Документи з вимогами є одним з найбільш граматично чутливих жанрів в інженерії програмного забезпечення. Погано сформоване вимога не просто погано читати - це створює неоднозначність, яка може призвести до неправильної речі, спорів у договорі, і невдалих приймальних тестів. Зрозуміти граматичні шаблони, які виробляють точні, однозначні вимоги, є практичною інженерною навичкою.

Цей посібник містить ключові граматичні вибірки для написання вимог: дієслова, модальні дієслова і/ або логіка, голос і форматування списку.

---

Простий теперішній vs. Буде

Простий теперішній час для поведінки системи

При описі того, що робить система — її звичайна поведінка — використовуйте теперішній простий час. Це стандарт у функціональних вимогах.

• «Система ** перевіряє ** адресу електронної пошти користувача перед створенням облікового запису.»
• API ** повертає ** код стану 404, коли запитуваного ресурсу не існує
• «Платіжна служба ** відсилає ** електронну пошту з підтвердженням протягом 30 секунд після успішної транзакції.»

Простий теперішній час описує безчасну правду про систему — не те, що вона зробить в майбутньому, або що вона зробила в минулому, але те, що вона робить як питання її визначеної поведінки.

Буде для зобов’ язань (старий стиль)

Старіші документи з вимогами, особливо в уряді, обороні і регульованих галузях, використовують « shall » для визначення обов’ язкових вимог:

• «Система shall аутентифікує користувачів через OAuth 2.0.»
• «Програма зберігає паролі як солені геш-коду за допомогою bcrypt.»

«Буде» в цьому контексті означає «обов’язково» — це не маркер майбутнього часу, а маркер обов’язку. Якщо ви зустрінетесь з цією нормою у вашій організації, використовуйте її постійно. Якщо ви починаєте з нуля, сучасна конвенція RFC 2119 щодо написання MUST (великими літерами) є більш зрозумілою.

Складання іменників: поширена помилка

Поєднання теперішнього часу простого з майбутнім часом простим (« буде » ) у одному документі створює плутанину щодо того, чи ви описуєте поточну поведінку, чи майбутню поведінку.

• Неоднозначний: «Система перевіряє вхідні дані. Він поверне помилку, якщо вхідний даний невірний.”
• Clear: « Система перевіряє введення. Він повертає помилку, якщо вхідний даний є невірним»

Використовуйте « will » лише у тому випадку, якщо вам необхідно чітко вказати майбутню зміну або відповідь на подію, яка призвела до зміни: « Після того, як користувач натисне кнопку Переслати, система покаже індикатор завантаження ». Навіть у цьому випадку простий теперішній час зазвичай є більш зрозумілим: « Після того, як користувач натисне кнопку Переслати, система покаже індикатор завантаження »

---

Уникнення неоднозначності з «І» / «Або»

«І» і «або» є одними з найнебезпечніших слів у документах з вимогами, тому що їх логічне значення часто неоднозначне в природній англійській мові. Юридичне та технічне письмо має певні конвенції для виключення цієї неоднозначності.

Проблема неоднозначності

«Система приймає VISA, Mastercard і Amex» — це означає, що система повинна приймати всі три, або що вона приймає принаймні одну з трьох? В англійській прозі це читається як «все три» через послідовну кому. Все гаразд.

Але зауважте: « Користувачі повинні вказати чинну адресу електронної пошти і номер телефону або офіційний документ, що посвідчує особу ». Чи означає це:

• (ел. пошта І телефон) ТА (урядовий ідентифікатор)
• електронна пошта І (телефон АБО державний ідентифікаційний код)

Це справді неоднозначно. Розробник і менеджер продукту, які читають це речення, можуть реалізувати зовсім іншу логіку.

Як розв’язати це

** Варіант 1: Переписати, щоб вилучити сполучення. **

Замість: «Користувачі повинні надати чинну адресу електронної пошти і номер телефону або виданий урядом ідентифікатор»

Напишіть: « Користувачі повинні надати або (а) чинну адресу електронної пошти і чинний номер телефону, або (б) державний ідентифікаційний код. »

** Варіант 2: Використовувати пронумеровані підвимоги. **

The user must provide at least one of the following to verify their identity:
1. A valid email address AND a valid phone number
2. A government-issued ID

** Варіант 3: Використовуйте « і/ або » явно. **

«Система записує помилки і/або попередження до служби моніторингу.» — Це явно означає одне, інше або обидва.

Однак, «і/або» не є заміною для чіткого мислення. Використовуйте його лише тоді, коли обидва випадки справді стосуються.

«Інший» і «Інший» (англ

• “Система приймає ** або ** API ключ ** або ** символ носія.” — один або інший, а не обидва
• “Запит повинен включати ** як ** ідентифікатор користувача ** і ** знак сеансу.” — обидва обов’язкові

Використання цих структур явно вилучає неоднозначність з вимог, що вимагають багато сполучень.

---

Активний проти. Пасивний голос у специфікаціях

Коли використовувати активний голос

Активний голос називає суб’ єкта, який виконує дію. У вимогах, суб’єкт зазвичай є «системою», «користувачем», або певним компонентом.

• «Система перевіряє токени на кожному запиті.»
• «Користувач вибирає спосіб оплати зі спадного списку.»
• ”** API-шлюз ** автентифікує запит перед тим, як маршрутизувати його до backend-сервісу.”

Активний голос ясно говорить про відповідальність. Це робить очевидним, який компонент має робити що.

Коли пасивно- мовний голос є відповідним

Пасивний голос прийнятний у вимогах, коли актор невідомий, незначний, або коли отримувач дії є фокусом.

• « Паролі ** зберігаються ** як геш-код bcrypt. » — фокус на форматі зберігання, а не на тому, який компонент зберігає їх
• “Записи журналу ** зберігаються ** протягом 90 днів.” — політика зберігання є вимогою; механізм є вторинним
• « Неуспішні спроби входу записуються в журнал аудиту. » — прийнятно, якщо відповідальність за запис встановлена в іншому місці

Пассивная ловушка голоса

Пасивний голос у вимогах може приховати відповідальність і створити суперечки про те, хто відповідальний за реалізацію вимоги.

• Неоднозначне: « Сеанс завершується після 30 хвилин бездіяльності. » — який компонент завершує його?
• Clear: « Служба керування сеансами завершує сеанс після 30 хвилин бездіяльності користувача. »

Якщо є можливість неоднозначності щодо відповідальності, скористайтеся активним голосом і вкажіть відповідальний компонент.

---

Номеровані списки для точності

Вимоги до прози важче посилатися, тестувати і аудиторії, ніж структуровані списки. Використання пронумерованих списків перетворює абзац вимог на перевіряємі, посилання на які можна робити елементи.

До: вимоги до прози

«Реєстраційна форма повинна перевірити, що адреса електронної пошти є в чинному форматі, що пароль має принаймні вісім символів і містить принаймні одну велику літеру, одну малу літеру і одну цифру, і що користувач погодився з умовами використання»

Це містить щонайменше п’ять окремих вимог, упакованих в одне речення. Це важко перевірити, важко посилатися на це в звіті про помилку («не вдалося вимога три»), і легко частково пропустити.

Після: вимоги до нумерованого списку

The registration form MUST validate all of the following before submission:

1. The email address conforms to RFC 5321 format.
2. The password is at least 8 characters in length.
3. The password contains at least one uppercase letter (A–Z).
4. The password contains at least one lowercase letter (a–z).
5. The password contains at least one numeric digit (0–9).
6. The user has checked the "I agree to the Terms of Service" checkbox.

Тепер кожна вимога незалежно перевіряється. Неуспішний тест прийняття може точно посилатися на «вимогу 4». Переглядач коду може перевіряти кожен елемент окремо.

Ієрархічні вимоги

Для складних систем використовувати ієрархічну нумерацію:

3. Authentication Requirements
   3.1 The system MUST support OAuth 2.0 authentication.
   3.2 The system MUST support API key authentication for service-to-service calls.
   3.3 The system SHOULD support SAML 2.0 for enterprise customers.
      3.3.1 SAML metadata MUST be configurable per tenant.
      3.3.2 The system MUST support both IdP-initiated and SP-initiated flows.

Ця структура робить вимоги навигаційними, відстежуваними і аудиторськими.

---

Граматичний контрольний список для документів з вимогами

Перед надсиланням або публікацією документа з вимогами, перевірте наступні пункти:

• Всі обов’ язкові вимоги використовують MUST або « shall » послідовно
• Для всіх рекомендованих, але необов’ язкових вимог використовуйте SHOULD або MAY
• Не використовувати конструкції « і/ або », якщо їх намір не зрозумілий
• Комплексні сполучення розв’ язуються за допомогою пронумерованих альтернатив
• Активний голос використовується у всіх випадках, коли відповідальним за виконання програми є певний компонент
• Вимоги пронумеровані і незалежно перевіряються
• Час є послідовним (теперішній простий для поведінки системи)

Точність у граматиці вимог не є педантикою — це різниця між функцією, яка побудована правильно, і функцією, побудованою за неправильною специфікацією.