docs: сняты проверки над проверками

- Из «Любой узел» в review.md убраны три свойства о годности самих проверок:
  мутация теста, мутация оракула критерия, требование без сценария.
- Из go-linters.md снята «Лестница механизации», ссылки на неё переписаны
  в конвенциях, их индексе и журнале дефектов.
This commit is contained in:
av
2026-08-13 16:45:12 +03:00
parent cb65967389
commit 539ed926cb
3 changed files with 21 additions and 63 deletions
+9 -39
View File
@@ -15,11 +15,11 @@
исходники.
Пока язык у проекта один, и запись названа по нему. Появится второй — у него
будет своя запись, а лестница и два круга останутся общими.
будет своя запись, а два круга останутся общими.
Устройство ниже **переносимо**: разделы «Лестница механизации», «Два круга» и
«Как заводят новое правило» — не особенность transcriber и переносятся в другой
Go-проект как есть. Своё здесь — перечень правил и подавлений.
Устройство ниже **переносимо**: разделы «Два круга» и «Как заводят новое
правило» — не особенность transcriber и переносятся в другой Go-проект как есть.
Своё здесь — перечень правил и подавлений.
## Границы: где что живёт
@@ -48,37 +48,6 @@ Go-проект как есть. Своё здесь — перечень пра
механики и мало пользы. Долгом это больше не числится — задача
`migrations-step-norm-and-tests` закрыта без реализации.
## Лестница механизации
Свойство поднимается по ступеням, и ступень выбирают не по вкусу, а по тому,
чем свойство выражается. Верхняя ступень дешевле нижней в эксплуатации и дороже
в заведении, поэтому прыгать через ступень без нужды не надо.
1. **Проза конвенции.** Свойство названо словами, проверяет человек на каждом
ревью заново. Это ступень по умолчанию и худшая из всех: она стоит внимания
каждого прогона и молча перестаёт работать, когда внимание кончилось.
2. **Настройка готового линтера.** Свойство совпало с чужим правилом —
включается строкой в `.golangci.yml`. Дешевле всего; ограничение в том, что
правило чужое и говорит о том, о чём его написали.
3. **Запрет по имени** (`forbidigo`, `depguard`). Свойство выражается через «эту
функцию/пакет тут звать нельзя». Дешёво и точно, но требует **единой точки**,
куда запрещённое переносят: запрет без дома оставляет код без способа сделать
нужное.
4. **Тест-сканер исходников** (`internal/archrules`). Свойство — о структуре, а
не о вызове: направление зависимостей, согласованность двух перечней,
отсутствие идиомы. Пишется руками на `go/parser` или регулярном выражении,
зато читается как тест и ломается заметно.
5. **Свой шаг проверки** (`scripts/`, шаги `Taskfile.yml`). Свойство выходит за
пределы кода на Go: версия инструмента, форма `Dockerfile`, раскладка
документов. Дороже всех — у шага появляется своя норма и свои тесты.
Ступень, выбранная неверно, видна сразу. Запрет по имени, обходимый одной
лишней строкой, — на деле правило четвёртой ступени, оформленное как правило
третьей: так было с правилом о
заголовках ответа, которое сначала запретило текст `\.Header\(\)\.Get`, а
обходилось присваиванием в переменную. Правило переписано на суждение **по типу
приёмника** (`analyze-types`), и это уже настоящая третья ступень.
## Два круга: pre-commit и гейт
Проверки идут двумя кругами, и круг выбирается по цене прогона.
@@ -199,8 +168,8 @@ Go-проект как есть. Своё здесь — перечень пра
остаётся то, чему нет ни готового правила, ни детерминированного оракула:
уровень лога по адресату, единая логирующая точка на доменной границе, словарь
имён полей, канонический вид идентификатора, естественные ключи у деталей.
Свойство, оставшееся прозой, проверяет человек на каждом ревью заново — это и
есть первая ступень лестницы, и подъём с неё всегда выигрыш.
Свойство, оставшееся прозой, проверяет человек на каждом ревью заново, и правило,
снявшее с него эту работу, всегда выигрыш.
Названы поимённо и **остатки правил** — то, что правило не ловит и потому
осталось человеку:
@@ -242,8 +211,9 @@ Go-проект как есть. Своё здесь — перечень пра
Порядок один и тот же, и последние два шага пропускать нельзя.
1. **Найти дом.** Ступень лестницы выбирается по тому, чем свойство
выражается, а не по тому, что проще включить.
1. **Найти дом.** Дом выбирается по тому, чем свойство выражается, а не по тому,
что проще включить: настройка готового линтера, запрет по имени, тест-сканер
исходников или свой шаг набора проверок.
2. **Написать причину рядом.** Правило без причины снимают при первом же
неудобстве: тот, кто снимает, не знает, что оно ловило.
3. **Починить находки, а не подавить.** Подавление годится, когда правило