15. Язык описания¶
Часть RENAR Standard v1.1 · ← Оглавление
Нормативные разделы артефактов описания — BR, SR, SPEC, TC-нормы, ADAPT, ACTZ — пишутся контролируемым диалектом естественного языка: закрытый список модальных операторов, глоссарная дисциплина, запрещённые конструкции, атомарность и формы по типу артефакта. Глава нормирует текст артефактов проекта; текст самого стандарта нормирует редакционная политика reference/06. Основание — ADR-026; источники приёмов — ASD-STE100, EARS, RFC 2119 / 8174, INCOSE Guide for Writing Requirements, Attempto Controlled English, RuleSpeak, Gherkin (reference/11).
15.1 Зачем¶
Стандарт нормирует, какие артефакты создаются и как они связаны (глава 6, глава 8, глава 9); утверждение внутри артефакта до сих пор нормировалось одной формой (§6.6.3.1). Свободная проза порождает четыре класса дефектов, которые обнаруживаются поздно — на QG-2 или у клиента:
- широта прочтения — фраза допускает несколько прочтений, агент выбирает одно без сигнала о выборе;
- неверифицируемость — «система должна быть удобной» не переводится в Pass-критерий;
- терминологический дрейф — один смысл назван разными словами по цепочке BR → SR → SPEC → TC;
- накопление неоднозначности по той же цепочке через
constrained-by[]иsource.*.
Язык описания — не формальный язык (без парсера, читаем человеком) и не свободная проза: набор дисциплин, проверяемых чтением — человеком при состязательном обзоре и агентом при генерации.
15.1.1 Нормативный раздел¶
Правила главы действуют в нормативных разделах тел артефактов: «Потребность», «Критерии успеха» и «Ограничения» BR (§6.5.3); «Требование», «Поведение», «Ограничения» SR (§6.6.3); type-specific разделы SPEC (§8.5); Pass- и Fail-критерии, предусловия и шаги TC (§9.4); пункты ACTZ (§7.13); прямая интерпретация ADAPT (§7.4.3). Свободные разделы — «Контекст», обоснования, история версии — подчиняются только §15.2 (операторы) и §15.3 (термины); переписка внутри ACTZ (текст клиента) правилам главы не подчиняется.
Адрес утверждения. Утверждение — предложение нормативного раздела. Утверждения одного артефакта нумеруются сквозь его нормативные разделы в порядке следования; адрес утверждения — <id>#<n> (например, SR-10#5). Нумерация выводится из текста и в нём не хранится; вставка предложения сдвигает номера — это правка утверждения, видимая в записи версии (§10.5.4). Адресом пользуются verifies[].statement TC-нормы (§9.3), ref шага сценария (§8.5.12.1) и проверка покрытия версии (§10.11.1).
15.2 Модальные операторы (закрытый список)¶
| Оператор | RFC 2119 | Семантика |
|---|---|---|
| должен | MUST / SHALL |
Абсолютное требование; невыполнение — дефект |
| не должен | MUST NOT / SHALL NOT |
Абсолютный запрет |
| следует | SHOULD |
Требование по умолчанию; отступление допустимо при явном обосновании в том же артефакте |
| не следует | SHOULD NOT |
Запрет по умолчанию; исключение обосновывается там же |
| допускается | MAY |
Истинно опциональное поведение; обоснования не требует |
Список закрыт (§1.7.5, строка 17). Три правила:
- Единственность формы. В нормативном разделе обязательность выражается только оператором из списка; синонимы («обязан», «необходимо», «нужно», «важно, чтобы», «желательно», «стоит», «может») запрещены. Однозначность даёт закрытость списка, а не начертание: операторы пишутся обычной орфографией — прописные в русской прозе запрещены (reference/06 §2.1, п. 4), опознаётся оператор списком и позицией, как маркеры форм §6.6.3.1. Глагол согласуется по роду и числу с подлежащим («система должна», «поля должны»).
- Один оператор на утверждение. В одном нормативном предложении — ровно один оператор. «Должен, но допускается» — два утверждения, требующие разделения (§15.5).
- «Допускается», а не «может». Слово «может» двусмысленно между способностью и разрешением («система может обработать 1000 запросов» — способность или право?) и в нормативных разделах не употребляется.
Английская редакция артефакта использует прописные MUST / MUST NOT / SHOULD / SHOULD NOT / MAY по RFC 8174 — конвенция, которую понимает оснастка (reference/en/06); соответствие между редакциями — по таблице выше.
15.3 Глоссарная дисциплина¶
- Один термин — одно определение — одна форма. Каждый термин, значимый для прочтения утверждения (роль, состояние, единица измерения, сущность системы), определён один раз — в разделе сопоставления терминов ADAPT (§7.4) либо при первом употреблении в комплекте — и далее употребляется только в этой форме.
- Синонимы одного понятия запрещены по цепочке BR → SR → SPEC → TC. Два артефакта, называющие одну сущность по-разному («проверка» и «валидация»), — не стилистический вариант, а обратная находка категории
terminology(§7.4.4); в артефактах, происходящих из ТЗ, она проходит контрактный контур по общим правилам. - Единицы измерения обязательны при каждом числовом значении и одинаковы по всему артефакту (всегда «мс», не «мс» в одном месте и «секунды» в другом).
- Аббревиатура раскрывается при первом употреблении в артефакте, далее употребляется только сокращённая форма; аббревиатуры закрытого списка стандарта (
BR,SR,SPEC,TC,ADAPT,ACTZ,QG) раскрытия не требуют.
Термины самого стандарта подчиняются §4.2; их дрейф в артефакте — класс 4.11.5 (§4.11).
15.4 Запрещённые конструкции¶
Каждое вхождение переформулируется до утверждения версии комплекта. Список закрыт в пределах главы; дополнение — через изменение стандарта.
| # | Запрещено | Почему | Плохо | Хорошо |
|---|---|---|---|---|
| 1 | Оценочное слово без критерия: «удобный», «быстрый», «достаточный», «современный», «интуитивно понятный» | Неверифицируемо | Система должна работать быстро | Система должна вернуть ответ не более чем за 300 мс |
| 2 | Лазейка: «по возможности», «при необходимости», «в разумных пределах», «где применимо» | Документированное оправдание невыполнения | Ошибки логируются по возможности | Система должна записать каждую ошибку в журнал errors.log |
| 3 | Знак «/» как связка «и / или» | Неясно, союз это или альтернатива | Поле обязательно/опционально | Пользователь должен заполнить поле. Если значение отсутствует, то система должна подставить null |
| 4 | Недостижимый абсолют без допуска: «всегда», «никогда», «100 %», «полностью» | Буквально непроверяемо | Система никогда не теряет данные | Система должна сохранять данные с надёжностью не ниже 99,99 % на интервале 30 дней |
| 5 | «Все / любой / оба» вместо поэлементного квантора | Неясно, коллективно утверждение или для каждого элемента | Все поля должны проходить валидацию | Каждое поле формы должно пройти валидацию по своему правилу |
| 6 | Местоимение без однозначного антецедента в том же предложении: «это», «он», «она» | Утверждение теряет самодостаточность — агент читает по частям | Пользователь отправляет форму. Она должна быть провалидирована | Система должна провалидировать форму до отправки |
| 7 | Отрицательное требование без позитивного измеримого критерия: «не должен зависать» | Не задаёт проверяемого поведения | Интерфейс не должен зависать | Система должна отобразить индикатор ожидания, если ответ не получен за 200 мс |
| 8 | Связка «и / или / затем / если не», соединяющая разные условия или действия | Два требования склеены в одно | Система проверяет права и логирует попытку, если доступ запрещён | (1) Система должна проверить права доступа. (2) Если доступ запрещён, то система должна записать попытку в журнал |
| 9 | Страдательный залог без субъекта действия | Неясно, кто действует — ответственность не распределена | Заявка должна быть одобрена | Менеджер должен одобрить заявку |
| 10 | Придаточное, присоединённое не к тому слову, к которому относится | Неоднозначность привязки | Пользователь получает уведомление о заявке, которая была отклонена | Если заявка отклонена, то пользователь должен получить уведомление об отклонении |
Информативный список слов reference/04 §3.2 — иллюстрация строк 1 и 2; норма — здесь.
15.5 Атомарность утверждения¶
Одно нормативное предложение — одна проверяемая мысль.
Критерий. Утверждение неатомарно и должно быть разбито, если для его проверки необходима более чем одна пара TC-норм — позитивная и негативная (§13.3.5); для негативного инварианта — более чем одна TC-норма. Признаки: больше одного оператора в предложении; союз «и» соединяет два действия или два условия, а не однородные дополнения одного действия; предложение отвечает сразу на два вопроса «что должно произойти».
Длина. Утверждению следует умещаться в 25 слов. Превышение — признак склейки, а не повод сокращать текст в ущерб смыслу.
15.6 Формы по типу артефакта¶
Формы — рекомендация в v1.1 (следует), с пересмотром модальности по практике (ADR-022, ADR-026); правила §15.2–§15.5 действуют независимо от формы.
15.6.1 SR и SPEC¶
Утверждения о поведении системы в SR и в type-specific разделах SPEC принимают одну из шести форм §6.6.3.1: постоянная, по состоянию («Пока …»), событийная («Когда …»), нежелательного поведения («Если …, то …»), опциональной возможности («При наличии …»), составная («Пока …, когда …»). Слово «система» заменяется точным именем компонента, если утверждение адресовано ему, а не системе целиком (§15.4, строка 9).
15.6.2 BR¶
«Потребность» — форма «кто, что, зачем» (§6.5.3). Раздел «Ограничения» BR — бизнес-правила в четырёх формах:
| Форма | Шаблон | Пример |
|---|---|---|
| Обязательство | ‹Субъект› должен ‹действие› | Клиент должен подтвердить оплату до начала работ |
| Запрет | ‹Субъект› не должен ‹действие› | Подрядчик не должен привлекать субподрядчика без письменного согласования |
| Ограниченное разрешение | ‹Субъекту› допускается ‹действие›, только если ‹условие› | Клиенту допускается запросить возврат, только если заявка подана в течение 14 дней |
| Условное обязательство | Если ‹условие›, то ‹субъект› должен ‹действие› | Если сумма превышает 500 000 ₽, то менеджер должен эскалировать заявку |
«Только если» при ограниченном разрешении обязательно: без него неясно, обязательное это условие или одно из допустимых. «Критерии успеха» — 3–7 измеримых атомарных утверждений.
15.6.3 TC¶
Тело TC нормировано семью разделами §9.4; тройка «Дано — Когда — Тогда» читается как три из них: Дано → Предусловия, Когда → Шаги, Тогда → Pass-критерий. Fail-критерий — перечень наблюдаемых признаков нарушения, не отрицание Pass (§9.11). Для system и contract шагам следует содержать одно действие или одно событие; несколько действий — несколько TC. Journey-TC (ux, SPEC-UC) многошаговы по определению — ограничение на них не распространяется.
15.6.4 ADAPT и ACTZ¶
Прямая интерпретация ADAPT — проза под §15.2–§15.5; допустима форма от лица анализа («интерпретируется как …»). Пункт ACTZ — обязательство перед клиентом: форма обязательства («кнопка называется …», «срок — 72 часа») без интерпретирующих оговорок; вопрос, требующий решения клиента, ставится вопросом, а не предположением (§7.13).
15.7 Применение и проверка¶
- Правила §15.2–§15.5 обязательны с уровня
RENAR-2(§11.5); формы §15.6 — рекомендация. - Проверка — часть состязательного обзора (§7.10.2) и предусловие утверждения версии комплекта: нарушение оформляется замечанием к формулировке и устраняется до утверждения (§10.7.2). Само по себе языковое нарушение не является обратной находкой — та фиксирует расхождение смысла; исключение — синоним, породивший терминологический конфликт (§15.3, п. 2).
- Статическая проверка правил (список операторов, конструкции строк 2–5 и 8 §15.4, длина) рекомендуется как
automation.kind: static(§9.8.1); гейтом стандарта она не является. - Изменение списка операторов или форм — изменение стандарта (§13.9); ранее утверждённые версии комплекта задним числом не переформулируются.
15.8 Язык записи¶
Артефакт на русском языке пишется по-русски целиком, кроме: идентификаторов и аббревиатур закрытых списков стандарта (BR, SR, SPEC-*, TC, ADAPT, ACTZ, QG-N, V1–V6); имён полей схем (source.tz-section, constrained-by[]). Маркеры форм §6.6.3.1 в русском артефакте — русские, обычной орфографией. Правило совпадает с политикой корпуса — reference/06 §1.
15.9 Пример: до и после¶
До:
Система должна быстро обрабатывать заявки. Если что-то пошло не так, она должна корректно сообщить об этом пользователю и/или залогировать ошибку. Все заявки обрабатываются менеджером, который должен по возможности отвечать в разумные сроки.
После:
Когда пользователь отправляет заявку, система должна вернуть подтверждение приёма не более чем за 2 секунды. Если обработка заявки завершается ошибкой, то система должна отобразить пользователю сообщение об ошибке. Если обработка заявки завершается ошибкой, то система должна записать ошибку в журнал
errors.log. Менеджер должен ответить на каждую заявку не позднее 24 часов с момента поступления.
Одно предложение «до» стало четырьмя утверждениями: три формы §6.6.3.1, одно бизнес-правило §15.6.2; у каждого — ровно одна пара TC.
15.10 Связь с другими главами¶
| Глава | Связь |
|---|---|
| 01 Область применения | Закрытый список операторов — §1.7.5, строка 17 |
| 04 Термины | Термины стандарта — §4.2; дрейф терминологии — класс 4.11.5 |
| 06 Иерархия требований | Формы утверждения SR — §6.6.3.1; тело BR — §6.5.3 |
| 07 ADAPT | Сопоставление терминов; категория terminology; форма пунктов ACTZ — §7.13 |
| 09 Тест-кейсы | Разделы тела TC — §9.4; Pass / Fail — §9.11 |
| 10 Жизненный цикл и QG | Проверка языка — предусловие утверждения версии, §10.7.2 |
| 11 Модель зрелости | Обязательность с RENAR-2 — §11.5 |
| 13 Соответствие | Пара TC на утверждение — §13.3.5; изменение списков — §13.9 |
| reference/04 | Информативный лексикон и шаблоны для AI-генератора |
| reference/06 | Редакционная политика текста стандарта (не артефактов) |