dev-conventions/READING.md

---
version: 1
---

# Как читать конвенцию

Файлы рядом с этим — конвенции: правила о том, как в этом репозитории пишут
код. Здесь сказано, как они записаны: что означают заглавные слова, из чего
состоит правило и как на него сослаться. Читается один раз, дальше нужен как
справка.

Файл кладёт сюда сборщик конвенций и перезаписывает целиком при каждом
обновлении. Правки в нём не живут.

## Ключевые слова

Заглавное слово в начале абзаца задаёт обязательность правила.

| Слово | Что означает | Если делаем иначе |
|---|---|---|
| **ДОЛЖЕН** | нарушение считается ошибкой | только с записью в отступления |
| **НЕ ДОЛЖЕН** | запрет, та же строгость | то же |
| **СЛЕДУЕТ** | сильная рекомендация: новый код пишем так | допустимо, причину записываем |
| **НЕ СЛЕДУЕТ** | обратное к СЛЕДУЕТ | то же |
| **ДОПУСКАЕТСЯ** | выбор за автором кода | ничего не требуется — правило не запрещает |

Две вещи, которые легко прочитать неверно:

- **ДОПУСКАЕТСЯ — не бытовое «можно».** У слова есть вторая половина: выбор,
  помеченный им, на ревью не обсуждается. Возражение «сделай иначе» против
  такого выбора не принимается — иначе разрешение ничего не значило бы.
- **Отступление от ДОЛЖЕН — не запрет на отступление.** Нарушать можно, но
  тогда об этом появляется запись: какое правило, где именно, почему. Разница
  между ДОЛЖЕН и СЛЕДУЕТ — в том, чем платят за отклонение, а не в том,
  возможно ли оно.

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

Заглушка со СНЯТО занимает место убранного правила вместе с его номером:
так нумерация остаётся сплошной, а ссылка на снятое правило приводит к
объяснению, а не в пустоту. Требований в такой заглушке нет.

```markdown
### XLOG-4. Уровень записи выбирался по громкости отказа

**СНЯТО 2026-05-14.** Заменено на XLOG-8: громкость каждый оценивал
по-своему, и шкала расползалась.
```

**Нормативно только заглавное написание.** Строчное «должен» в прозе — обычная
речь, а не норма; спорить с ней как с правилом не нужно.

## Из чего состоит правило

Правило в примере вымышленное: префиксы на `X` общий набор не занимает
никогда, поэтому пример нельзя спутать с настоящим правилом.

```markdown
### XLOG-8. Уровень выбирается по адресату

**ДОЛЖЕН.** Уровень отвечает на вопрос «кому сообщение», а не «насколько
громко сломалось».

| № | Уровень | Кому и когда |
|---|---|---|
| XLOG-8.1 | `DEBUG` | разработчику при отладке; в проде выключен |
| XLOG-8.2 | `INFO` | владельцу, аудит постфактум |

**ПОЧЕМУ.** Адресат — единственный признак, по которому разные авторы в
разных местах кода выберут уровень одинаково…
```

- **Идентификатор и заголовок.** `XLOG-8` — адрес правила: по нему на правило
  ссылаются, им помечают отступления и механизацию.
- **Модальность с нормой.** Собственно требование, одной фразой. Таблица или
  список сразу за модальным словом — часть нормы: она уточняет вердикт, и на
  её строку ссылаются номером (`XLOG-8.2`).
- **ПОЧЕМУ.** Зачем правило существует и что сломается, если сделать иначе.
  Обоснование ничего не требует — по нему решают, применимо ли правило к
  случаю, и видно, когда причина отпала.
- **ПРИМЕРЫ** — необязательный последний блок: код, обычно парой «плохо →
  хорошо». Иллюстрация, а не спецификация: деталь примера требованием не
  становится, дословно копировать его не нужно, а если пример разошёлся с
  нормой — действует норма.

**Правило кончается перед следующим заголовком.** Абзацы после ПОЧЕМУ — это
продолжение обоснования: примеры, разбор границ, ссылки на внешние практики.
Требований в них нет; всё, что подлежит исполнению, стоит в блоке нормы.

## Как ссылаться

- На **правило** — идентификатором: `XLOG-27`. Путь к файлу не нужен,
  идентификатор уникален.
- На **конвенцию целиком** — именем темы: конвенция `logging`. Имя темы стоит
  в шапке файла (`origin:`).
- Строка таблицы адресуется номером с точкой: `XLOG-8.2`.

## Что ниже маркера

```markdown
<!-- conv:local -->
```

Всё выше маркера приезжает из общего набора и перезаписывается при
обновлении. Всё ниже принадлежит этому репозиторию и обновление переживает.
Там живёт:

- **отступления** — какое правило не соблюдается, где и почему: «`XMIG-6` не
  соблюдается в `queue`: составные ключи там появились до конвенции»;
- **механизация** — кто проверяет правило машинно: «`XMIG-4` —
  МЕХАНИЗИРОВАНО: `internal/archrules`»;
- **разрешение условий**, которые правило оставило открытыми;
- **свои правила** — по той же форме, но с префиксом на `X` (`XLOG-1`).
  Префиксы на `X` общий набор не занимает никогда, так что столкнуться они не
  могут.

Правка выше маркера живёт до первого обновления и исчезает молча. Если
исправить нужно приехавший текст — либо правку переносят в общий набор, либо
файл перестаёт быть копией: из шапки убирают `origin:`.

## Чего в конвенции не бывает

- **Утверждений о том, как сейчас устроен этот репозиторий.** Правило пишется
  в предписывающем времени; «у нас пока не так» — это отступление, и его
  место ниже маркера.
- **Заглавных ключевых слов вне правил.** Во вводной прозе, в разделах
  «Область действия» и «Связано» их нет, поэтому искать там требования не
  нужно.

Язык записи — версия 1. Полное описание живёт в наборе конвенций, у автора;
здесь ровно то, что нужно читателю.