язык: примеры переведены на вымышленные X-правила
- живые идентификаторы KEYS-5, SLOG-8.1, SLOG-27, MIGR-2/4/6 в примерах заменены на XKEY, XMIG, XLOG: номера канона означали не то, что в примере, и расходились дальше при каждой перенумерации - сказано явно, что описание языка ни на один набор конвенций не опирается; ссылка на обоснования канона в разделе про ПОЧЕМУ заменена на внешние практики
This commit is contained in:
+19
-13
@@ -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`: составные
|
||||
ключи там появились до конвенции, переписывание требует миграции данных.
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user