diff --git a/CLAUDE.md b/CLAUDE.md index 88ff7f3..92c0c33 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,6 +39,10 @@ code in this repository. Исключение — строка о версии языка, которая их перечисляет. - «Почему» отвечает на «что сломается, если сделать иначе», а не пересказывает норму. «Потому что так принято» — не обоснование. +- Служебные слова сценарного блока — тоже словарь набора: **КОГДА**, + **ТОГДА**, **И**, **ИЛИ** (по-английски `WHEN`/`THEN`/`AND`/`OR`). Одна + форма на роль, заглавными. Модальностью не являются, в строку о версии + языка не попадают. - Правило, классифицирующее ситуации, пишется таблицей «ситуация → вердикт»; строки нумеруются `KEYS-5.1`. Строки взаимоисключающи по умолчанию; иной порядок объявляется явно, а перечисленные случаи покрывают область diff --git a/LANGUAGE.md b/LANGUAGE.md index ad4e33d..2250ec7 100644 --- a/LANGUAGE.md +++ b/LANGUAGE.md @@ -24,8 +24,8 @@ version: 1 | **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` как общая форма записи | +| **EARS** | вывод о том, что выигрыш даёт жёсткий шаблон, а не его конкретный вид; паттерн «нежелательное поведение» — в виде таблицы | шаблоны как форма записи правила: `WHEN`, `WHILE`, `WHERE` | +| **OpenSpec** | четырёхчастная форма правила; адресуемость правила идентификатором; форма «условие → следствие» для стыка правил | `SHALL`; `GIVEN/WHEN/THEN` как общая форма записи | Три отклонения стоят объяснения, потому что выглядят как произвол. @@ -40,12 +40,17 @@ version: 1 контракт, которого конвенция не даёт. Для англоязычного словаря это означает выбор в пользу `MUST` из BCP 14, а не `shall` из ISO/IEC Directives. -**`GIVEN/WHEN/THEN` не берётся.** У спецификации субъект — система, и её -поведение разворачивается во времени: состояние, событие, исход. У конвенции -субъект — автор кода, и разворачивать нечего: есть ситуация выбора и вердикт. -Это таблица, а не траектория. Тем же рассуждением отклонены шаблоны EARS с -субъектом-системой, а взят из EARS другой результат: измеримый выигрыш дала -там сама обязательность шаблона, а не его конкретная форма. +**`GIVEN/WHEN/THEN` не берётся как общая форма.** У спецификации субъект — +система, и её поведение разворачивается во времени: состояние, событие, +исход. У конвенции субъект — автор кода, и разворачивать нечего: есть +ситуация выбора и вердикт. Это таблица, а не траектория. Тем же рассуждением +отклонены шаблоны EARS как форма записи правила, а взят из EARS другой +результат: измеримый выигрыш дала там сама обязательность шаблона, а не его +конкретная форма. + +Исключение — стык правил, где субъект действительно система: там форма +«условие → следствие» берётся сознательно, вместе со служебными словами под +неё. Это единственное место, и оно описано в «Таблицах решений». ## Что даёт формализация @@ -158,9 +163,14 @@ Directives, Part 2, по одной форме записи на ступень, ## Словарь другого языка -Для английского готовый словарь даёт BCP 14. Для любого другого языка слова -берут из перевода стандарта, если он есть, или переводят сами: шкала и -семантика ступеней при этом не меняются — меняется только запись. +Словарь набора — это два перечня: модальные слова и служебные слова +сценарного блока (`КОГДА`, `ТОГДА`, `И`, `ИЛИ` — см. «Таблицы решений»). +Требования к ним одни и те же. + +Для английского готовый словарь модальных слов даёт BCP 14. Для любого +другого языка слова берут из перевода стандарта, если он есть, или переводят +сами: шкала и семантика ступеней при этом не меняются — меняется только +запись. | Ступень | Русский | Английский (BCP 14) | |---|---|---| @@ -264,17 +274,37 @@ Directives, Part 2, по одной форме записи на ступень, возможен случай вне перечисленных, он назван отдельной строкой, а не оставлен на догадку. -Прозаический сценарий остаётся точечным инструментом — для **стыка правил**, -когда два правила вместе дают неочевидный результат: +Сценарный блок остаётся точечным инструментом — для **стыка правил**, когда +два правила вместе дают неочевидный результат: ``` -WHEN зависимость недоступна и ретраи вызова исчерпаны → ext-запись ERROR -AND тик фонового цикла упал по той же причине → доменная запись WARN +КОГДА зависимость недоступна И ретраи вызова исчерпаны +ТОГДА внешний вызов даёт запись ERROR, +И тик фонового цикла, упавший по той же причине, — запись WARN ``` Такой блок ставится после обоих правил и ссылается на их идентификаторы. Если стыков нет — сценариев в файле нет. +Форма «условие → следствие» здесь взята намеренно, хотя как **общая** форма +записи она отклонена: на стыке правил субъект действительно система, и +результат разворачивается во времени — то самое, для чего эта форма и +придумана. Служебные слова блока перечислены ниже и подчиняются тем же +требованиям, что модальные: одна форма на роль, заглавными, набор один на +канон. + +| Роль | Русский | Английский | +|---|---|---| +| условие | КОГДА | WHEN | +| следствие | ТОГДА | THEN | +| соединение | И | AND | +| выбор | ИЛИ | OR | + +Модальными словами они не являются: обязательности не задают, только +структуру. Поэтому в строку о версии языка они не попадают — там +перечисляется то, чему нужно определение, а логическая связка читается сама, +— и под проверку «модальные слова вне правил» не подпадают. + ## Идентификаторы - Формат — `<ПРЕФИКС>-<номер>`: `KEYS-5`, `SLOG-27`. Префикс принадлежит @@ -340,8 +370,8 @@ MIGR-6 не соблюдается в легаси-таблицах `show_histor Разбором текста: -- модальные слова принадлежат объявленному словарю канона, а не смеси - словарей; +- модальные и служебные слова принадлежат объявленному словарю канона, а не + смеси словарей; - префикс в шапке файла совпадает с реестром, состоит из четырёх заглавных латинских букв, не начинается на `X` и не значится в списке выбывших; - заголовки правил файла используют только его собственный префикс; diff --git a/TODO.md b/TODO.md index bb4a897..548631b 100644 --- a/TODO.md +++ b/TODO.md @@ -107,33 +107,7 @@ Go-бинарь со своим релизным циклом, ставить ч нечего обслуживать. Сначала 4, потом 5. Разделение из вопроса 1 при этом дешевле заложить сразу, чем отпиливать потом. -## 6. `WHEN`/`AND` в блоке стыка правил - -Блок для стыка двух правил записан английскими словами: - -``` -WHEN зависимость недоступна и ретраи вызова исчерпаны → ext-запись ERROR -AND тик фонового цикла упал по той же причине → доменная запись WARN -``` - -Рядом сказано, что `SHALL` не берётся ни в один словарь, потому что занят -OpenSpec. `WHEN` и `AND` — из того же набора и по той же причине должны бы -не браться, но взяты. Это нестыковка, а не решение. - -Варианты: - -- **перевести** на `КОГДА` / `И`: словарь набора один, и служебные слова - внутри канона следуют ему же; -- **оставить и объяснить**: блок стыка описывает поведение системы во - времени, а не выбор автора, — то есть это единственное место, где форма - спецификации уместна, и заимствование её синтаксиса намеренно. - -Второе честнее по смыслу (субъект там действительно система), но требует -явной оговорки в `LANGUAGE.md`, иначе читается как недосмотр. Заодно решить, -подпадают ли `WHEN`/`AND` под проверку «заглавные модальные слова не -встречаются вне правил»: сейчас формально нет, потому что в словаре их нет. - -## 7. Критерий «названного вреда» никого не обязывает +## 6. Критерий «названного вреда» никого не обязывает `LANGUAGE.md` говорит, что ДОЛЖЕН требует двух условий сразу: нарушение причиняет названный вред (критерий BCP 14) и норма проверяема машиной @@ -147,7 +121,7 @@ OpenSpec. `WHEN` и `AND` — из того же набора и по той ж META-6 её защищает. Против: критерий «вред назван» проверяется чтением, а не машиной, — то есть по META-6 сам он может быть только СЛЕДУЕТ. -## 8. Одиннадцать таблиц не прочитаны на взаимоисключительность +## 7. Одиннадцать таблиц не прочитаны на взаимоисключительность `LANGUAGE.md` объявил, что строки таблицы решений взаимоисключающи по умолчанию, а иной порядок объявляется явно. Объявление не делает таблицы @@ -162,7 +136,7 @@ META-6 её защищает. Против: критерий «вред назв Работа читательская, машине не даётся; в список проверок она уже записана в разделе «Чтением, потому что машине не даётся». -## 9. Возможность, записанная модальным словом +## 8. Возможность, записанная модальным словом Четвёртая категория ISO — возможность и осуществимость — ключевого слова не имеет: такие утверждения пишутся обычной прозой. Значит канон надо просмотреть diff --git a/conventions/lang/go/logging.md b/conventions/lang/go/logging.md index 34e55f4..4684e5b 100644 --- a/conventions/lang/go/logging.md +++ b/conventions/lang/go/logging.md @@ -411,10 +411,10 @@ ctx = logctx.With(ctx, log) // достаём логгер из ctx в кажд уровень доменной записи об исходе тика. ``` -WHEN зависимость недоступна и ретраи вызова исчерпаны - → ext-запись `ERROR` (SLOG-29.4) -AND тик фонового цикла упал по той же причине - → доменная запись `WARN` (SLOG-27) +КОГДА зависимость недоступна И ретраи вызова исчерпаны +ТОГДА ext-запись `ERROR` (SLOG-29.4) +И тик фонового цикла, упавший по той же причине, + даёт доменную запись `WARN` (SLOG-27) ``` Из этого следует, что у лежащей зависимости `ext`-запись пишет `ERROR`