dev-conventions/READING.md

version

version
1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<!-- conv:local -->

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

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

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

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

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

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