--- version: 1 --- # Язык конвенций Формальный язык, на котором записаны правила этого канона: что считается правилом, чем оно отличается от прозы вокруг, какими словами задаётся обязательность и как на правило сослаться извне. Версия языка — **1**. Номер называется в каждой конвенции: словарь может пополниться, и текст, написанный по предыдущей версии, должен читаться по той, по которой написан. ## Опора на стандарты Язык не выводится из вкуса автора. Каждое решение о форме взято из документа, где эта задача уже решена и обкатана, и отклонения от источника названы явно. | Источник | Что взято | Что отклонено | |---|---|---| | **BCP 14** (RFC 2119 + RFC 8174) | шкала модальности; правило «нормативно только заглавное»; сдержанность в высшей модальности; англоязычный словарь как готовый | синонимы `REQUIRED`, `RECOMMENDED`, `OPTIONAL`; `SHALL` как форма требования | | **ISO/IEC Directives, Part 2** | разделение «требование — рекомендация — разрешение — возможность»; запрет модальных глаголов в утверждениях о факте | списки равнозначных словесных форм («is to», «is required to», «only … is permitted») | | **ISO/IEC/IEEE 29148** | обоснование как обязательный атрибут; единичность нормы; проверяемость; метод верификации отдельным атрибутом | остальной аппарат требований: приоритеты, источники, матрицы трассируемости | | **DMN** | таблица решений с объявленной политикой совпадения и требованием полноты | исполняемая семантика и всё, что предполагает движок решений | | **EARS** | вывод о том, что выигрыш даёт жёсткий шаблон, а не его конкретный вид; паттерн «нежелательное поведение» — в виде таблицы | шаблоны как форма записи правила: `WHEN`, `WHILE`, `WHERE` | | **OpenSpec** | четырёхчастная форма правила; адресуемость правила идентификатором; форма «условие → следствие» для стыка правил | `SHALL`; `GIVEN/WHEN/THEN` как общая форма записи | Три отклонения стоят объяснения, потому что выглядят как произвол. **Синонимов нет.** BCP 14 держит `REQUIRED` рядом с `MUST` и `OPTIONAL` рядом с `MAY` ради читаемости английской прозы. Одна форма записи на ступень означает, что проверка «модальное слово употреблено вне правила» становится перечислением, а не разбором синонимических рядов. **`SHALL` не используется ни в каком словаре этого языка.** Слово занято спецификациями (OpenSpec), и общая с ними форма стирала бы границу между конвенцией и описанием поведения системы: `SHALL` в конвенции читался бы как контракт, которого конвенция не даёт. Для англоязычного словаря это означает выбор в пользу `MUST` из BCP 14, а не `shall` из ISO/IEC Directives. **`GIVEN/WHEN/THEN` не берётся как общая форма.** У спецификации субъект — система, и её поведение разворачивается во времени: состояние, событие, исход. У конвенции субъект — автор кода, и разворачивать нечего: есть ситуация выбора и вердикт. Это таблица, а не траектория. Тем же рассуждением отклонены шаблоны EARS как форма записи правила, а взят из EARS другой результат: измеримый выигрыш дала там сама обязательность шаблона, а не его конкретная форма. Исключение — стык правил, где субъект действительно система: там форма «условие → следствие» берётся сознательно, вместе со служебными словами под неё. Это единственное место, и оно описано в «Таблицах решений». ## Что даёт формализация Адресуемое правило — не украшение формы, а условие работы трёх механизмов: - **Механизация.** Запись о ней должна говорить «правило `MIGR-4` проверяет `archrules`», а не «`AUTOINCREMENT` в новых миграциях — `archrules`»: во втором случае читатель сам догадывается, к какому утверждению это относится, и догадывается по-разному. - **Отступления.** «У нас не так» бесполезно, пока не сказано, что именно «не так». Со ссылкой на правило отступления становятся счётными: видно, сколько правил конвенции репозиторий реально не соблюдает. - **Промоут находки.** Путь «находка → конвенция → правило линтера → удаление прозы» требует ручки, за которую берут конкретное правило. Общий знаменатель — **идентификатор**. Модальные слова и таблицы полезны, но вторичны. ## Единица — правило ```markdown ### KEYS-5. Разбор внешнего идентификатора на границе **ДОЛЖЕН.** Идентификатор, пришедший снаружи, проходит разбор до запроса к базе. **ПОЧЕМУ.** Разбор валидирует формат и нормализует регистр. Сравнение строк в базе побайтовое, поэтому без нормализации запрос молча не находит существующую запись — отладка такого случая стоит дороже, чем сам разбор. ``` Четыре обязательные части: **идентификатор**, **заголовок**, **модальность с нормой**, **обоснование под меткой ПОЧЕМУ**. Норма — одна фраза; если в неё не влезает, это два правила. Требование единичности взято из ISO/IEC/IEEE 29148: составная норма не проверяема целиком, и нарушение одной её половины нечем адресовать. Обе метки правила — модальное слово и ПОЧЕМУ — пишутся заглавными и принадлежат словарю набора: скелет правила читается одинаково в любом языке, на который канон переведён. ## Обоснование обязательно Правило без блока ПОЧЕМУ не принимается. Это требование к форме, а не пожелание; в 29148 обоснование — атрибут требования наравне с самим требованием, и по тем же причинам: - **Обоснование — единственный способ увидеть, что правило устарело.** Норма стареет молча; причина стареет заметно. Когда причина отпала, видно, что правило пора убрать, а не соблюдать по инерции. - **Правило без обоснования не переживает спор.** Через год ни автор, ни агент не восстановят мотив, и правило будет либо отменено первым же возражением, либо соблюдено там, где вредит. - **Формулировка обоснования — проверка на то, что это вообще правило.** Если причина не формулируется, перед нами привычка или вкусовщина; ей место в черновиках, а не в конвенции. Обоснование отвечает на «что сломается, если сделать иначе», а не пересказывает норму другими словами. «Потому что так принято» — не обоснование. Форма обоснования при этом ничем не ограничена: рамки здесь только смысловые. Абзац может быть длинным, вести рассуждение, приводить пример, ссылаться на внешние практики, стандарты и чужие проекты — канон это уже делает («адаптация OpenTelemetry», «как по умолчанию в zap и zerolog», двенадцатишаговая процедура SQLite). Запрещённых слов и обязательной структуры у обоснования нет, и заводить их не нужно: обязательность несёт норма, а обоснование её объясняет — путаницу между этими двумя ролями исключает правило о заглавных. ## Модальные слова Инвариант языка — **шкала**: пять ступеней в четырёх категориях ISO/IEC Directives, Part 2, по одной форме записи на ступень, заглавными. Какими словами ступени названы — параметр естественного языка набора, а не часть языка конвенций. Этот канон написан по-русски и несёт русский словарь. Пишутся заглавными — это ключевые слова, а не обычный текст. | Слово | Категория | Значение | Отступление | |---|---|---|---| | **ДОЛЖЕН** | требование | нарушение считается ошибкой | только с записью в отступления | | **НЕ ДОЛЖЕН** | требование | запрет | то же | | **СЛЕДУЕТ** | рекомендация | сильная рекомендация; новый код пишем так | допустимо, причину записываем | | **НЕ СЛЕДУЕТ** | рекомендация | обратное к СЛЕДУЕТ | то же | | **ДОПУСКАЕТСЯ** | разрешение | выбор за автором кода; возражение на ревью не принимается | не требуется — правило ничего не запрещает | **Нормативно только заглавное написание.** Это правило RFC 8174, и оно здесь по той же причине, по которой понадобилось там: без него каждое строчное «должен» во вводной прозе становится предметом спора о том, норма это или речь. Строчное слово нормой не является никогда, поэтому проза свободна, а проверка «модальное слово вне правила» сводится к поиску заглавных форм. **Четвёртая категория ISO — возможность — ключевого слова не имеет.** Утверждения о том, что бывает и что технически осуществимо, пишутся обычной прозой и модальных слов не несут. Модальное слово в таком утверждении превращает описание в норму, которую никто не собирался вводить. **ДОПУСКАЕТСЯ адресовано рецензенту.** В BCP 14 у `MAY` есть вторая половина, которую обычно не замечают: сторона, не выбравшая опцию, обязана работать с той, что выбрала. В конвенции этому соответствует запрет возражать: выбор, помеченный ДОПУСКАЕТСЯ, на ревью не обсуждается. Без этой половины слово было бы удобством читателя, а не нормой, и не работало бы в единственной точке, где у конвенции есть принуждение. **ДОЛЖЕН требует двух условий сразу:** 1. нарушение причиняет названный вред, а не расходится со вкусом — META-25, он же критерий BCP 14, где высшая модальность резервируется под то, что действительно ломается, и не употребляется для навязывания метода; 2. норма проверяема машиной — META-6, иначе обязательность держится на внимании и обещает то, чего не делает. Не выполнено первое — правилу место в СЛЕДУЕТ или нигде. Не выполнено второе — в СЛЕДУЕТ. Проверяемость сама по себе не повышает правило до ДОЛЖЕН: механически проверяемых мелочей больше, чем важных вещей, и безразборное повышение обесценивает шкалу быстрее, чем её отсутствие. Модальность живёт на **правиле**, а не на файле. Файловый статус (`status: рекомендуемая` / `обязательная` в шапке) не используется: он неизбежно врёт, потому что один файл смешивает жёсткие требования с советами. В шапке остаются только `prefix` и `extends`. ## Словарь другого языка Словарь набора — три перечня, и требования к ним одни и те же. **Шкала обязательности.** Для английского готовый словарь даёт BCP 14; для любого другого языка слова берут из перевода стандарта, если он есть, или переводят сами. Шкала и семантика ступеней при этом не меняются — меняется только запись. | Ступень | Русский | Английский (BCP 14) | |---|---|---| | требование | ДОЛЖЕН | MUST | | запрет | НЕ ДОЛЖЕН | MUST NOT | | рекомендация | СЛЕДУЕТ | SHOULD | | рекомендация против | НЕ СЛЕДУЕТ | SHOULD NOT | | разрешение | ДОПУСКАЕТСЯ | MAY | **Метки правила.** Обязательности не задают, а размечают его части. Стандартом не даются ни в одном языке: в BCP 14 таких понятий нет, слова подбираются под язык так же, как остальные. | Метка | Русский | Английский | |---|---|---| | обоснование | ПОЧЕМУ | WHY | | способ проверки | МЕХАНИЗИРОВАНО | MECHANIZED | **Служебные слова сценарного блока** — `КОГДА`, `ТОГДА`, `И`, `ИЛИ`; таблица и объяснение в разделе «Таблицы решений». Что требуется от любого словаря: - **одна форма на ступень и на метку.** Синонимы отклонены не из аскетизма: проверка «модальное слово вне правила» перечисляет формы, и синонимический ряд превращает перечисление в разбор. - **слово заглавными не встречается в обычной прозе этого языка.** Иначе правило «нормативно только заглавное» перестаёт спасать: проверка ловит оформление, а не модальность. - **модальные слова и метки перечислены в строке о версии языка.** Читателю копии они известны из самого файла, без обращения к этому документу, — иначе конвенция в чужом репозитории теряет ключ к собственному тексту. Служебные слова сценария в строку не входят: структура блока читается из самого блока, и в файле без стыков правил их нет вовсе. - **словарь один на канон.** Два словаря параллельно дают две формы записи одного требования и удваивают каждую проверку; выбор языка — свойство набора, а не отдельного файла. ## Ссылка на язык из конвенции Каждая конвенция называет язык одной строкой во вводной прозе: > Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки > ПОЧЕМУ и МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — > тогда и только тогда, когда написаны заглавными. Слова в строке — из словаря того языка, на котором написан набор. Для англоязычного набора та же строка выглядит так: > The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and the marks WHY > and MECHANIZED are to be interpreted as described in the conventions > language, version 1, and only when written in capitals. Форма скопирована у BCP 14, где та же задача решается тем же способом: спецификация не прикладывает к себе словарь и не указывает путь к нему, а называет документ и версию. Пути в этой строке нет намеренно — конвенция уезжает в чужой репозиторий, где путей канона не существует, а норму исполнить всё равно можно: строка сама перечисляет ключевые слова набора и сама несёт правило заглавных. ## Обязательность и способ проверки — разные атрибуты Механизация не входит в шкалу модальности: она говорит не о том, насколько правило обязательно, а о том, чем эта обязательность обеспечена. В 29148 это два разных атрибута требования, и здесь тоже два. Когда правило механизировано у всех потребителей, его норма из канона удаляется, а модальность и обоснование остаются: ```markdown ### MIGR-6. Дефолтов времени в схеме БД нет **ДОЛЖЕН. МЕХАНИЗИРОВАНО.** Проверяется общим правилом линтера; формулировка удалена, потому что дублировала работающую проверку. **ПОЧЕМУ.** Дефолт превращает забытую вставку в тихо работающий код… ``` - Идентификатор и заголовок сохраняются: ссылки из репозиториев продолжают указывать на то же утверждение. - Модальность сохраняется, поэтому «все ли ДОЛЖЕН механизированы» остаётся вычислимым вопросом, а не предметом чтения всего канона. - Обоснование остаётся навсегда — линтер сообщает, что нарушено, но не сообщает, зачем правило существует, и без обоснования нельзя понять, когда проверку пора отменять. Факт «механизировано у всех» устанавливается вручную: канон по построению не знает списка подписчиков, и обойти репозитории перед удалением нормы — часть работы, а не то, что можно проверить автоматически. ## Таблицы решений Часть правил **классифицирует ситуации**: какой уровень лога, какая категория директории, что делать с невалидным вводом в зависимости от его источника. Каноническая форма для них — таблица «ситуация → вердикт», строки которой нумеруются как подпункты правила (`SLOG-8.1`). Таблица плотнее прозы и не даёт пропустить ветку: пустая клетка видна, а неупомянутый случай в абзаце — нет. Два свойства такой таблицы взяты из DMN, где они называются и проверяются: - **Политика совпадения.** По умолчанию строки взаимоисключающи: любой ситуации соответствует ровно одна. Если это не так, таблица объявляет порядок строкой над собой — «применяется первое совпадение». Молчание об этом означает, что при двух подходящих строках читатель выбирает сам, и два автора выберут по-разному. - **Полнота.** Перечислены все случаи, попадающие в область действия. Если возможен случай вне перечисленных, он назван отдельной строкой, а не оставлен на догадку. Сценарный блок остаётся точечным инструментом — для **стыка правил**, когда два правила вместе дают неочевидный результат: ``` КОГДА зависимость недоступна И ретраи вызова исчерпаны ТОГДА внешний вызов даёт запись ERROR, И тик фонового цикла, упавший по той же причине, — запись WARN ``` Такой блок ставится после обоих правил и ссылается на их идентификаторы. Если стыков нет — сценариев в файле нет. Форма «условие → следствие» здесь взята намеренно, хотя как **общая** форма записи она отклонена: на стыке правил субъект действительно система, и результат разворачивается во времени — то самое, для чего эта форма и придумана. Служебные слова блока перечислены ниже и подчиняются тем же требованиям, что модальные: одна форма на роль, заглавными, набор один на канон. | Роль | Русский | Английский | |---|---|---| | условие | КОГДА | WHEN | | следствие | ТОГДА | THEN | | соединение | И | AND | | выбор | ИЛИ | OR | Модальными словами они не являются: обязательности не задают, только структуру. Поэтому в строку о версии языка они не попадают — там перечисляется то, чему нужно определение, а логическая связка читается сама, — и под проверку «модальные слова вне правил» не подпадают. ## Идентификаторы - Формат — `<ПРЕФИКС>-<номер>`: `KEYS-5`, `SLOG-27`. Префикс принадлежит файлу, нумерация внутри файла сквозная и начинается с единицы. - Строка таблицы, если на неё нужно ссылаться отдельно, — `KEYS-5.1`, `KEYS-5.2`. - **Идентификатор глобален.** Префикс уникален по всему канону, поэтому путь файла в ссылке не нужен: `KEYS-5` адресует правило одинаково изнутри файла, из соседней конвенции и из чужого репозитория. В собранной копии слои разных осей лежат в одном документе, так что ссылка на базовый слой из языкового вообще никуда не ведёт — правило рядом. - **Идентификаторы стабильны и не переиспользуются.** Удалённое правило оставляет дыру в нумерации; занимать её новым нельзя — иначе ссылка из чужого репозитория начнёт указывать на другое утверждение. То же относится к префиксам: выбывшие хранит `prefixes.toml`. - Префикс **выбирается под файл, а не выводится по формуле**: он нужен, чтобы по нему искать, а не чтобы его разбирать. Выводимый префикс вдобавок привязал бы идентификатор к таксономии, которую канон перестраивает, и упёрся бы в потолок из числа букв алфавита. - Префиксы на букву `X` каноном не занимаются: они принадлежат локальным правилам репозиториев-потребителей. - Перенос правила в другой файл — смысловое изменение, а не переименование: новый файл означает новый префикс и новую нумерацию. Переезд самого файла между осями идентификаторы не трогает. Порядок правил в файле выбирается по читаемости, не по номерам: номер — это идентификатор, а не позиция. ## Что правилом не является Заглавные модальные слова в этих частях **не употребляются** — иначе перестанет быть понятно, что адресуемо, а что нет: - **Область действия** — на что конвенция распространяется во времени («новые таблицы; существующие не переписываются»). Это рамка для всех правил файла, а не правило. - **Связано** — ссылки на смежные конвенции, ADR, код. - **Локальная часть копии** — содержимое принадлежит репозиторию. - Вводная проза, объясняющая предмет конвенции. ## Как на правила ссылаются копии Ниже маркера локальной части, в репозитории: ```markdown MIGR-2, MIGR-4 механизированы — `internal/archrules` (проверяются в новых миграциях). MIGR-6 не соблюдается в легаси-таблицах `show_history`, `queue`: составные ключи там появились до конвенции, переписывание требует миграции данных. ``` Отсюда видно и то, чего раньше не было видно: конвенция из восьми правил, из которых два механизированы и одно не соблюдается. ## Что стоит проверять машиной Проверки применяются к файлам конвенций; обвязка канона в них не входит — она ключевые слова цитирует, а не употребляет. Ни одна пока не реализована, поэтому при ревью их выполняют чтением. Разбором текста: - модальные и служебные слова принадлежат объявленному словарю канона, а не смеси словарей; - префикс в шапке файла совпадает с реестром, состоит из четырёх заглавных латинских букв, не начинается на `X` и не значится в списке выбывших; - заголовки правил файла используют только его собственный префикс; - номера уникальны внутри файла и не имеют пропусков вниз (новое правило берёт следующий свободный, а не первый освободившийся); - у каждого `### <ПРЕФИКС>-` есть модальное слово и блок ПОЧЕМУ; отметка МЕХАНИЗИРОВАНО стоит рядом с модальностью, а не вместо неё; - вводная проза содержит строку о версии языка; - ссылки вида `<ПРЕФИКС>-` — хоть в тексте канона, хоть в локальной части копии — указывают на правила, которые ещё существуют; - префиксы локальных правил копии начинаются на `X`; - заглавные модальные слова не встречаются вне правил — кроме строки о версии языка, которая их перечисляет по назначению; - префикс **чужой темы** не встречается в абзаце с модальностью (META-20); префикс арх-слоя своей темы там допустим (META-24), префикс другого языка или стека — нет; - путь файла канона не встречается в тексте конвенции (META-21). Чтением, потому что машине не даётся: - строки таблицы взаимоисключающи либо политика совпадения объявлена; - перечисленные в таблице случаи покрывают область действия; - норма исполнима без обращения к другим файлам; - обоснование отвечает на «что сломается», а не пересказывает норму. ## Версия языка Номер версии называется в каждой конвенции, поэтому он двигается, когда изменение формы способно изменить чтение **уже разданной** копии: копия ссылается на номер, а не на текст, и обязана читаться по той версии, по которой написана. Правки формы до того, как копии разошлись, номер не двигают — читать по ним пока нечего. Смена словаря под другой естественный язык версию не двигает никогда: версия принадлежит шкале, меткам и правилам формы, а не буквам.