язык: примеры переведены на вымышленные X-правила

- живые идентификаторы KEYS-5, SLOG-8.1, SLOG-27, MIGR-2/4/6 в примерах
  заменены на XKEY, XMIG, XLOG: номера канона означали не то, что в примере,
  и расходились дальше при каждой перенумерации
- сказано явно, что описание языка ни на один набор конвенций не опирается;
  ссылка на обоснования канона в разделе про ПОЧЕМУ заменена на внешние
  практики
This commit is contained in:
av
2026-07-26 15:15:30 +03:00
parent df8c58671f
commit d5118336cb
2 changed files with 41 additions and 52 deletions
+19 -13
View File
@@ -12,6 +12,12 @@ version: 1
пополниться, и текст, написанный по предыдущей версии, должен читаться по
той, по которой написан.
Описание языка ни на один набор конвенций не опирается, поэтому все примеры
здесь — вымышленные правила с префиксами на `X` (`XKEY`, `XMIG`, `XLOG`).
Такие префиксы канон не занимает никогда, реестру они не принадлежат — значит
пример не спутать с настоящим правилом, а перенумерация конвенций описание
языка не задевает.
## Опора на стандарты
Язык не выводится из вкуса автора. Каждое решение о форме взято из
@@ -56,7 +62,7 @@ version: 1
Адресуемое правило — не украшение формы, а условие работы трёх механизмов:
- **Механизация.** Запись о ней должна говорить «правило `MIGR-4` проверяет
- **Механизация.** Запись о ней должна говорить «правило `XMIG-4` проверяет
`archrules`», а не «`AUTOINCREMENT` в новых миграциях — `archrules`»: во
втором случае читатель сам догадывается, к какому утверждению это
относится, и догадывается по-разному.
@@ -72,7 +78,7 @@ version: 1
## Единица — правило
```markdown
### KEYS-5. Разбор внешнего идентификатора на границе
### XKEY-5. Разбор внешнего идентификатора на границе
**ДОЛЖЕН.** Идентификатор, пришедший снаружи, проходит разбор до запроса
к базе.
@@ -153,9 +159,9 @@ version: 1
Форма обоснования при этом ничем не ограничена: рамки здесь только
смысловые. Абзац может быть длинным, вести рассуждение, приводить пример,
ссылаться на внешние практики, стандарты и чужие проекты — канон это уже
делает («адаптация OpenTelemetry», «как по умолчанию в zap и zerolog»,
двенадцатишаговая процедура SQLite). Запрещённых слов и обязательной
ссылаться на стандарты, внешние практики и чужие проекты — на устройство
OpenTelemetry, на умолчания библиотек логирования, на процедуру миграции из
документации СУБД. Запрещённых слов и обязательной
структуры у обоснования нет, и заводить их не нужно: обязательность несёт
норма, а обоснование её объясняет — путаницу между этими двумя ролями
исключает правило о заглавных.
@@ -306,7 +312,7 @@ Directives, Part 2, по одной форме записи на ступень,
удаляется, а модальность и обоснование остаются:
```markdown
### MIGR-6. Дефолтов времени в схеме БД нет
### XMIG-6. Дефолтов времени в схеме БД нет
**ДОЛЖЕН. МЕХАНИЗИРОВАНО.** Проверяется общим правилом линтера;
формулировка удалена, потому что дублировала работающую проверку.
@@ -331,7 +337,7 @@ Directives, Part 2, по одной форме записи на ступень,
Часть правил **классифицирует ситуации**: какой уровень лога, какая
категория директории, что делать с невалидным вводом в зависимости от его
источника. Каноническая форма для них — таблица «ситуация → вердикт», строки
которой нумеруются как подпункты правила (`SLOG-8.1`).
которой нумеруются как подпункты правила (`XLOG-8.1`).
Таблица плотнее прозы и не даёт пропустить ветку: пустая клетка видна, а
неупомянутый случай в абзаце — нет. Два свойства такой таблицы взяты из DMN,
@@ -379,12 +385,12 @@ Directives, Part 2, по одной форме записи на ступень,
## Идентификаторы
- Формат — `<ПРЕФИКС>-<номер>`: `KEYS-5`, `SLOG-27`. Префикс принадлежит
- Формат — `<ПРЕФИКС>-<номер>`: `XKEY-5`, `XLOG-27`. Префикс принадлежит
файлу, нумерация внутри файла сквозная и начинается с единицы.
- Строка таблицы, если на неё нужно ссылаться отдельно, — `KEYS-5.1`,
`KEYS-5.2`.
- Строка таблицы, если на неё нужно ссылаться отдельно, — `XKEY-5.1`,
`XKEY-5.2`.
- **Идентификатор глобален.** Префикс уникален по всему канону, поэтому
путь файла в ссылке не нужен: `KEYS-5` адресует правило одинаково изнутри
путь файла в ссылке не нужен: `XKEY-5` адресует правило одинаково изнутри
файла, из соседней конвенции и из чужого репозитория. В собранной копии
слои разных осей лежат в одном документе, так что ссылка на базовый слой
из языкового вообще никуда не ведёт — правило рядом.
@@ -428,10 +434,10 @@ Directives, Part 2, по одной форме записи на ступень,
```markdown
<!-- conv:local -->
MIGR-2, MIGR-4 механизированы — `internal/archrules` (проверяются в новых
XMIG-2, XMIG-4 механизированы — `internal/archrules` (проверяются в новых
миграциях).
MIGR-6 не соблюдается в легаси-таблицах `show_history`, `queue`: составные
XMIG-6 не соблюдается в легаси-таблицах `show_history`, `queue`: составные
ключи там появились до конвенции, переписывание требует миграции данных.
```