av
170c06c1da
- заведён READING.md: словарь со значениями, форма правила и её граница, ссылки, локальная часть — без разделов о ведении набора и без META-ссылок, примеры на X-префиксах - сборщик кладёт его в docs/conventions/ и перезаписывает целиком; в манифест набора добавлена секция [language] с версией и двумя документами - META-30: правка словаря или состава частей правила доходит до READING.md, иначе потребитель толкует ДОПУСКАЕТСЯ по прежней версии
119 lines
7.9 KiB
Markdown
119 lines
7.9 KiB
Markdown
---
|
|
version: 1
|
|
---
|
|
|
|
# Как читать конвенцию
|
|
|
|
Файлы рядом с этим — конвенции: правила о том, как в этом репозитории пишут
|
|
код. Здесь сказано, как они записаны: что означают заглавные слова, из чего
|
|
состоит правило и как на него сослаться. Читается один раз, дальше нужен как
|
|
справка.
|
|
|
|
Файл кладёт сюда сборщик конвенций и перезаписывает целиком при каждом
|
|
обновлении. Правки в нём не живут.
|
|
|
|
## Ключевые слова
|
|
|
|
Заглавное слово в начале абзаца задаёт обязательность правила.
|
|
|
|
| Слово | Что означает | Если делаем иначе |
|
|
|---|---|---|
|
|
| **ДОЛЖЕН** | нарушение считается ошибкой | только с записью в отступления |
|
|
| **НЕ ДОЛЖЕН** | запрет, та же строгость | то же |
|
|
| **СЛЕДУЕТ** | сильная рекомендация: новый код пишем так | допустимо, причину записываем |
|
|
| **НЕ СЛЕДУЕТ** | обратное к СЛЕДУЕТ | то же |
|
|
| **ДОПУСКАЕТСЯ** | выбор за автором кода | ничего не требуется — правило не запрещает |
|
|
|
|
Две вещи, которые легко прочитать неверно:
|
|
|
|
- **ДОПУСКАЕТСЯ — не бытовое «можно».** У слова есть вторая половина: выбор,
|
|
помеченный им, на ревью не обсуждается. Возражение «сделай иначе» против
|
|
такого выбора не принимается — иначе разрешение ничего не значило бы.
|
|
- **Отступление от ДОЛЖЕН — не запрет на отступление.** Нарушать можно, но
|
|
тогда об этом появляется запись: какое правило, где именно, почему. Разница
|
|
между ДОЛЖЕН и СЛЕДУЕТ — в том, чем платят за отклонение, а не в том,
|
|
возможно ли оно.
|
|
|
|
Ещё две метки заглавными: **ПОЧЕМУ** открывает обоснование правила,
|
|
**МЕХАНИЗИРОВАНО** стоит при записи о том, что правило проверяет линтер или
|
|
скрипт.
|
|
|
|
**Нормативно только заглавное написание.** Строчное «должен» в прозе — обычная
|
|
речь, а не норма; спорить с ней как с правилом не нужно.
|
|
|
|
## Из чего состоит правило
|
|
|
|
Правило в примере вымышленное: префиксы на `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. Полное описание живёт в наборе конвенций, у автора;
|
|
здесь ровно то, что нужно читателю.
|