язык: короткое описание для читателя копии едет в репозиторий
- заведён READING.md: словарь со значениями, форма правила и её граница, ссылки, локальная часть — без разделов о ведении набора и без META-ссылок, примеры на X-префиксах - сборщик кладёт его в docs/conventions/ и перезаписывает целиком; в манифест набора добавлена секция [language] с версией и двумя документами - META-30: правка словаря или состава частей правила доходит до READING.md, иначе потребитель толкует ДОПУСКАЕТСЯ по прежней версии
This commit is contained in:
+118
@@ -0,0 +1,118 @@
|
||||
---
|
||||
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. Полное описание живёт в наборе конвенций, у автора;
|
||||
здесь ровно то, что нужно читателю.
|
||||
Reference in New Issue
Block a user