язык: заведён блок ПРИМЕРЫ

- пятая, необязательная часть правила: код парой «плохо → хорошо» после обоснования; метка добавлена в словарь (EXAMPLES) и в строку о версии языка во всех тринадцати файлах - сказано, чем примеры не являются: требований в блоке нет, дословным сниппетом он не служит, при расхождении с нормой правят пример - READING.md обновлён по META-30, в машинные проверки добавлен порядок блоков, в читательские — что примеры норму не расширяют
2026-07-26 16:09:58 +03:00
parent 1d19e0357b
commit 59a1c23f55
16 changed files with 116 additions and 48 deletions
@@ -21,6 +21,9 @@ code in this repository.
 - Четыре обязательные части: `### <ПРЕФИКС>-<N>. Заголовок`, абзац
  `**МОДАЛЬНОСТЬ.** норма`, абзац `**ПОЧЕМУ.** …`. Правило без обоснования не
  принимается.
+- `**ПРИМЕРЫ.**` — необязательный пятый блок после обоснования: код парой
+  «плохо → хорошо». Иллюстрация нормы, а не спецификация — требований в блоке
+  нет, дословным сниппетом он не является, при расхождении действует норма.
 - Норма — одна фраза; если в неё не влезает, это два правила.
 - Область правила — от его заголовка до следующего заголовка любого уровня;
  метка открывает блок, блок длится до следующей метки или до конца области.
@@ -43,8 +46,9 @@ code in this repository.
  записи о механизации в локальной части копии (META-7).
 - META-8: норма не удаляется из канона никогда, чем бы её ни проверяли.
  Механизация её не заменяет и не сокращает.
- Метки правила — **ПОЧЕМУ**, **МЕХАНИЗИРОВАНО** и **СНЯТО** — тоже словарь
-  набора и перечислены в строке о версии языка наравне с модальными словами.
+- Метки правила — **ПОЧЕМУ**, **ПРИМЕРЫ**, **МЕХАНИЗИРОВАНО** и **СНЯТО** —
+  тоже словарь набора и перечислены в строке о версии языка наравне с
+  модальными словами.
 - META-30: правка словаря или состава частей правила доходит до `READING.md` —
  документа, который едет к потребителю. Словари двух описаний совпадают.
 - Заглавные модальные слова не употребляются вне правил: ни в «Область
@@ -16,8 +16,8 @@ prefix: META
 же.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 ## Область действия

@@ -118,12 +118,12 @@ version: 1
 ```

 Четыре обязательные части: **идентификатор**, **заголовок**, **модальность
-с нормой**, **обоснование под меткой ПОЧЕМУ**. Норма — одна фраза; если в неё
-не влезает, это два правила. Требование единичности взято из ISO/IEC/IEEE
-29148: составная норма не проверяема целиком, и нарушение одной её половины
-нечем адресовать.
+с нормой**, **обоснование под меткой ПОЧЕМУ**. Пятый блок, ПРИМЕРЫ,
+необязателен — о нём ниже. Норма — одна фраза; если в неё не влезает, это два
+правила. Требование единичности взято из ISO/IEC/IEEE 29148: составная норма
+не проверяема целиком, и нарушение одной её половины нечем адресовать.

-Обе метки правила — модальное слово и ПОЧЕМУ — пишутся заглавными и
+Метки правила — модальное слово, ПОЧЕМУ, ПРИМЕРЫ — пишутся заглавными и
 принадлежат словарю набора: скелет правила читается одинаково в любом языке,
 на который канон переведён.

@@ -149,9 +149,10 @@ version: 1

 Отсюда три следствия:

- **Хвост после ПОЧЕМУ — обоснование**, а не безымянная часть правила и не
-  проза вокруг. Требований в нём не живёт: то, что подлежит исполнению, стоит
-  в блоке нормы, где у него есть модальность и адрес. Требование, оставленное
+- **Хвост после ПОЧЕМУ — обоснование** до следующей метки или до конца
+  области, а не безымянная часть правила и не проза вокруг. Требований в нём
+  не живёт: то, что подлежит исполнению, стоит в блоке нормы, где у него есть
+  модальность и адрес. Требование, оставленное
  в хвосте, требованием не является — сослаться на него нельзя и отступление
  от него записать нельзя.
 - **Таблица и список после модальной метки — часть нормы.** Правило,
@@ -166,6 +167,58 @@ version: 1
 упоминания отличает положение: метка стоит первой в своём абзаце, полужирным
 и с точкой.

+## Примеры к правилу
+
+Пятый блок правила — необязательный, под меткой ПРИМЕРЫ. В нём код,
+показывающий норму в деле, обычно парой «плохо → хорошо». Стоит он после
+обоснования: сначала требование, потом причина, потом иллюстрация.
+
+````markdown
+### XKEY-5. Внешний идентификатор разбирается до обращения к базе
+
+**ДОЛЖЕН.** Значение, пришедшее снаружи, проходит разбор и нормализацию
+раньше, чем по нему делается запрос.
+
+**ПОЧЕМУ.** Синтаксически невалидное значение не может соответствовать
+записи, поэтому поход в базу за ним — заведомо холостой.
+
+**ПРИМЕРЫ.**
+
+Плохо — строка уходит в запрос как пришла:
+
+```go
+row := db.QueryRow("select … where id = ?", r.PathValue("id"))
+```
+
+Хорошо — разбор на границе, запроса при неудаче нет:
+
+```go
+id, err := ident.Parse(r.PathValue("id"))
+if err != nil {
+    return notFound(w)
+}
+row := db.QueryRow("select … where id = ?", id)
+```
+````
+
+**Пример иллюстрирует норму, а не задаёт её.** Три следствия, ради которых
+это сказано:
+
+- **требований в блоке нет.** Всё, что подлежит исполнению, стоит в блоке
+  нормы; деталь примера — имя переменной, конкретная функция, форма ответа —
+  требованием не становится. Разошёлся пример с нормой — действует норма, а
+  пример правят;
+- **это не готовый сниппет.** Код в примере сокращён до того, что показывает
+  правило: обработка ошибок, контекст, импорты в нём условны, и копировать его
+  дословно не нужно;
+- **пример стареет быстрее нормы.** Он привязан к сегодняшнему API, поэтому
+  расхождение примера с текущим кодом — повод поправить пример, а не отменять
+  правило.
+
+Блок необязателен: он окупается там, где норму словами описать дороже, чем
+показать, — форма вызова, структура записи в логе, раскладка файла. У правила
+про выбор границы или про уровень лога иллюстрировать нечего.
+
 ## Обоснование обязательно

 Правило без блока ПОЧЕМУ не принимается. Это требование к форме, а не
@@ -267,14 +320,16 @@ Directives, Part 2, по одной форме записи на ступень,
 | рекомендация против | НЕ СЛЕДУЕТ | SHOULD NOT |
 | разрешение | ДОПУСКАЕТСЯ | MAY |

-**Метки.** Обязательности не задают, а размечают: ПОЧЕМУ — часть правила,
-МЕХАНИЗИРОВАНО — запись о проверке в копии, СНЯТО — заглушку на месте
-убранного правила. Стандартом не даются ни в одном языке: в BCP 14 таких
-понятий нет, слова подбираются под язык так же, как остальные.
+**Метки.** Обязательности не задают, а размечают: ПОЧЕМУ — обоснование,
+ПРИМЕРЫ — иллюстрации к норме, МЕХАНИЗИРОВАНО — запись о проверке в копии,
+СНЯТО — заглушку на месте убранного правила. Стандартом не даются ни в одном
+языке: в BCP 14 таких понятий нет, слова подбираются под язык так же, как
+остальные.

 | Метка | Русский | Английский |
 |---|---|---|
 | обоснование | ПОЧЕМУ | WHY |
+| иллюстрации | ПРИМЕРЫ | EXAMPLES |
 | способ проверки | МЕХАНИЗИРОВАНО | MECHANIZED |
 | снятое правило | СНЯТО | RETIRED |

@@ -303,15 +358,15 @@ Directives, Part 2, по одной форме записи на ступень,
 Каждая конвенция называет язык одной строкой во вводной прозе:

 > Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-> ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-> версии 1 — тогда и только тогда, когда написаны заглавными.
+> ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+> конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 Слова в строке — из словаря того языка, на котором написан набор. Для
 англоязычного набора та же строка выглядит так:

 > The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and the marks WHY,
-> MECHANIZED and RETIRED are to be interpreted as described in the conventions
-> language, version 1, and only when written in capitals.
+> EXAMPLES, MECHANIZED and RETIRED are to be interpreted as described in the
+> conventions language, version 1, and only when written in capitals.

 Форма скопирована у BCP 14, где та же задача решается тем же способом:
 спецификация не прикладывает к себе словарь и не указывает путь к нему, а
@@ -530,6 +585,8 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor
 - у каждого `### <ПРЕФИКС>-<n>` есть либо модальное слово с нормой и блок
  ПОЧЕМУ — ни норма, ни обоснование не удаляются никогда (META-8, META-10), —
  либо блок СНЯТО с датой и причиной;
+- блок ПРИМЕРЫ, если он есть, стоит после обоснования и не открывает правило:
+  порядок блоков — норма, ПОЧЕМУ, ПРИМЕРЫ;
 - вводная проза содержит строку о версии языка;
 - ссылки вида `<ПРЕФИКС>-<n>` — хоть в тексте набора, хоть в локальной части
  копии — разрешаются: неразрешённый идентификатор всегда ошибка (META-32);
@@ -564,7 +621,9 @@ XMIG-6 не соблюдается в легаси-таблицах `show_histor
 - норма исполнима без обращения к другим файлам (в файлах конвенций: они
  уезжают по одной, а обвязка ссылается на соседей свободно);
 - обоснование отвечает на «что сломается», а не пересказывает норму;
- хвост обоснования не вводит требований, которых нет в блоке нормы.
+- хвост обоснования не вводит требований, которых нет в блоке нормы;
+- примеры иллюстрируют норму и не расширяют её: деталь примера не читается
+  как требование.

 ## Версия языка

@@ -34,9 +34,10 @@ version: 1
  между ДОЛЖЕН и СЛЕДУЕТ — в том, чем платят за отклонение, а не в том,
  возможно ли оно.

-Ещё три метки заглавными: **ПОЧЕМУ** открывает обоснование правила,
-**МЕХАНИЗИРОВАНО** стоит при записи о том, что правило проверяет линтер или
-скрипт, **СНЯТО** — на месте правила, которое убрали.
+Ещё четыре метки заглавными: **ПОЧЕМУ** открывает обоснование правила,
+**ПРИМЕРЫ** — код, показывающий норму в деле, **МЕХАНИЗИРОВАНО** стоит при
+записи о том, что правило проверяет линтер или скрипт, **СНЯТО** — на месте
+правила, которое убрали.

 Заглушка со СНЯТО занимает место убранного правила вместе с его номером:
 так нумерация остаётся сплошной, а ссылка на снятое правило приводит к
@@ -80,6 +81,10 @@ version: 1
 - **ПОЧЕМУ.** Зачем правило существует и что сломается, если сделать иначе.
  Обоснование ничего не требует — по нему решают, применимо ли правило к
  случаю, и видно, когда причина отпала.
+- **ПРИМЕРЫ** — необязательный последний блок: код, обычно парой «плохо →
+  хорошо». Иллюстрация, а не спецификация: деталь примера требованием не
+  становится, дословно копировать его не нужно, а если пример разошёлся с
+  нормой — действует норма.

 **Правило кончается перед следующим заголовком.** Абзацы после ПОЧЕМУ — это
 продолжение обоснования: примеры, разбор границ, ссылки на внешние практики.
@@ -12,8 +12,8 @@ prefix: DIRS
 механически выводится состав бэкапа.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 ## Область действия

@@ -9,8 +9,8 @@ prefix: CONF
 секретами и когда падает.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 ## Область действия

@@ -8,8 +8,8 @@ prefix: KEYS
 Как выбираются и как выглядят первичные ключи сущностей.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 ## Область действия

@@ -9,8 +9,8 @@ prefix: TIME
 берётся значение и где появляется не-UTC.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 ## Область действия

@@ -10,8 +10,8 @@ extends: arch/config.md
 запрета на окружение.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 Секретов Go-специфика не касается: они приходят из деплоя уже в файле, а
 проверка их непустоты идёт вместе с остальной валидацией — как описано в
@@ -9,8 +9,8 @@ extends: arch/db-identifiers.md
 Как базовый слой выглядит в Go-приложении.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 Единая точка из `KEYS-3` — пакет `internal/ident`: он
 порождает идентификаторы (`NewID`, `NewIDAt`) и он же их разбирает
@@ -9,8 +9,8 @@ prefix: MIGR
 Go-приложении.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 ## Область действия

@@ -10,8 +10,8 @@ prefix: GERR
 границе).

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 Две границы, о которых говорят правила ниже:

@@ -11,8 +11,8 @@ extends: arch/time.md
 функциональности, живут в спеках.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 Лог читают инструментами, а не глазами: повседневно — `jq`
 (`jq 'select(.download_id=="a1b2")' app.jsonl`), тяжёлое (агрегации, JOIN) —
@@ -10,8 +10,8 @@ extends: arch/time.md
 в каком виде время попадает в базу и в логи, что делать с зонами.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 ## Правила

@@ -9,8 +9,8 @@ extends: arch/app-directories.md
 Как категории из базового слоя раскладываются на сервере плейбуком.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 ## Область действия

@@ -10,8 +10,8 @@ prefix: HTMX
 какие действия поддерживает — в спеках, не здесь.

 Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
-ПОЧЕМУ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке конвенций
-версии 1 — тогда и только тогда, когда написаны заглавными.
+ПОЧЕМУ, ПРИМЕРЫ, МЕХАНИЗИРОВАНО и СНЯТО толкуются как описано в языке
+конвенций версии 1 — тогда и только тогда, когда написаны заглавными.

 Логирование запросов — конвенция `logging` (HTTP-поля, рутинно-частое на
 `DEBUG`). Трансляция доменных ошибок наружу — конвенция `errors`