guide: заведён META-26 — обоснование объясняет, а не требует
- «Почему» не пересказывает норму словами обязательства: у оригинала есть идентификатор, у копии нет, и расходятся они при первой правке оригинала, а отступление от копии адресовать нечем - модальность рекомендательная по META-6: греп находит слово, а не нарушение — «за попыткой следует повтор» и «становится обязанностью вызывающего» описывают ход событий; утверждения о невозможности («нельзя») правилом не затрагиваются, это ISO-евская возможность в прозе - SLOG-12 починен: факт о том, что `slog` не разделяет CRITICAL и FATAL, уехал из нормы в «Почему», а норма теперь говорит то же, что заголовок
This commit is contained in:
@@ -39,6 +39,10 @@ code in this repository.
|
|||||||
Исключение — строка о версии языка, которая их перечисляет.
|
Исключение — строка о версии языка, которая их перечисляет.
|
||||||
- «Почему» отвечает на «что сломается, если сделать иначе», а не
|
- «Почему» отвечает на «что сломается, если сделать иначе», а не
|
||||||
пересказывает норму. «Потому что так принято» — не обоснование.
|
пересказывает норму. «Потому что так принято» — не обоснование.
|
||||||
|
- META-26: «Почему» не повторяет норму словами обязательства — на неё
|
||||||
|
ссылаются идентификатором. Утверждения о невозможности (`нельзя`) — факт, а
|
||||||
|
не запрет, и допустимы. Модальность рекомендательная: греп по `должен`,
|
||||||
|
`обязан`, `следует` даёт кандидатов, но слова омонимичны.
|
||||||
- Служебные слова сценарного блока — тоже словарь набора: **КОГДА**,
|
- Служебные слова сценарного блока — тоже словарь набора: **КОГДА**,
|
||||||
**ТОГДА**, **И**, **ИЛИ** (по-английски `WHEN`/`THEN`/`AND`/`OR`). Одна
|
**ТОГДА**, **И**, **ИЛИ** (по-английски `WHEN`/`THEN`/`AND`/`OR`). Одна
|
||||||
форма на роль, заглавными. Модальностью не являются, в строку о версии
|
форма на роль, заглавными. Модальностью не являются, в строку о версии
|
||||||
|
|||||||
@@ -232,6 +232,25 @@ prefix: META
|
|||||||
существует. Без обоснования не видно, когда причина отпала, — проверка
|
существует. Без обоснования не видно, когда причина отпала, — проверка
|
||||||
продолжает работать по инерции, и возразить ей нечем, кроме как отключив.
|
продолжает работать по инерции, и возразить ей нечем, кроме как отключив.
|
||||||
|
|
||||||
|
### META-26. Обоснование объясняет, а не требует
|
||||||
|
|
||||||
|
**НЕ СЛЕДУЕТ.** Абзац «Почему» не повторяет норму словами обязательства — на
|
||||||
|
ту норму, на которую он опирается, ссылаются идентификатором.
|
||||||
|
|
||||||
|
**Почему.** Обоснование, сформулированное как требование, заводит вторую
|
||||||
|
копию нормы: у оригинала есть идентификатор, у копии нет, и расходятся они
|
||||||
|
при первой же правке оригинала. Читатель не отличает объяснение от
|
||||||
|
досказанной нормы, а отступление от копии не адресуемо — ссылаться на абзац
|
||||||
|
нечем.
|
||||||
|
|
||||||
|
Утверждения о невозможности («нельзя», «не выйдет») сюда не относятся: они
|
||||||
|
описывают, чего не бывает, а не то, что запрещено, и проза — их законное
|
||||||
|
место. Модальность здесь рекомендательная не по слабости, а по META-6:
|
||||||
|
машинная проверка даёт кандидатов, а не вердикт, потому что слова
|
||||||
|
омонимичны — «за попыткой следует повтор» и «присвоение становится
|
||||||
|
обязанностью каждого вызывающего» описывают ход событий. Вердикт остаётся за
|
||||||
|
чтением, грепу достаётся роль подсказки.
|
||||||
|
|
||||||
### META-11. У трудноизменяемого слоя область действия пишется явно
|
### META-11. У трудноизменяемого слоя область действия пишется явно
|
||||||
|
|
||||||
**ДОЛЖЕН.** Конвенция о схеме БД, формате хранения или раскладке директорий
|
**ДОЛЖЕН.** Конвенция о схеме БД, формате хранения или раскладке директорий
|
||||||
|
|||||||
+5
-1
@@ -395,4 +395,8 @@ MIGR-6 не соблюдается в легаси-таблицах `show_histor
|
|||||||
- строки таблицы взаимоисключающи либо политика совпадения объявлена;
|
- строки таблицы взаимоисключающи либо политика совпадения объявлена;
|
||||||
- перечисленные в таблице случаи покрывают область действия;
|
- перечисленные в таблице случаи покрывают область действия;
|
||||||
- норма исполнима без обращения к другим файлам;
|
- норма исполнима без обращения к другим файлам;
|
||||||
- обоснование отвечает на «что сломается», а не пересказывает норму.
|
- обоснование отвечает на «что сломается», а не пересказывает норму;
|
||||||
|
- обоснование не повторяет норму словами обязательства (META-26). Кандидатов
|
||||||
|
находит греп по `должен`, `обязан`, `следует`, `необходимо` в абзацах
|
||||||
|
«Почему», но вердикт остаётся за чтением: слова омонимичны — «за попыткой
|
||||||
|
следует повтор» требованием не является.
|
||||||
|
|||||||
@@ -122,16 +122,38 @@ Go-бинарь со своим релизным циклом, ставить ч
|
|||||||
Работа читательская, машине не даётся; в список проверок она уже записана в
|
Работа читательская, машине не даётся; в список проверок она уже записана в
|
||||||
разделе «Чтением, потому что машине не даётся».
|
разделе «Чтением, потому что машине не даётся».
|
||||||
|
|
||||||
## 7. Возможность, записанная модальным словом
|
## 7. Пересказ нормы в «Почему» — вычитать под META-26
|
||||||
|
|
||||||
Четвёртая категория ISO — возможность и осуществимость — ключевого слова не
|
Исходный вопрос («где факт записан модальным словом») закрыт по существу:
|
||||||
имеет: такие утверждения пишутся обычной прозой. Значит канон надо просмотреть
|
канон просмотрен, и такой ошибки в нём практически нет. Тринадцать строчных
|
||||||
на обратную ошибку: где утверждение о факте («библиотеки по умолчанию отдают
|
«нельзя» оказались корректными — это утверждения о невозможности, ISO-евская
|
||||||
именно его», «SQLite сравнивает строки побайтово») записано модальным словом
|
возможность в прозе, ровно как задумано. Единственный настоящий случай,
|
||||||
и тем самым превратилось в норму, которую никто не вводил.
|
SLOG-12, починен: факт про `slog` уехал в «Почему», норма повторяет свой
|
||||||
|
заголовок.
|
||||||
|
|
||||||
Смотреть в первую очередь абзацы «Почему»: там факты и стоят, там же соблазн
|
Зато нашёлся обратный класс, под который заведён META-26: норма пересказана
|
||||||
усилить их модальностью выше всего.
|
словами обязательства внутри «Почему». Греп даёт десять совпадений, из них
|
||||||
|
семь — кандидаты на правку, вердикт за чтением:
|
||||||
|
|
||||||
|
```
|
||||||
|
arch/db-identifiers.md:61 «Нормализация регистра (KEYS-4) … обязаны»
|
||||||
|
arch/time.md:43 «текстовому полю обязан давать порядок событий»
|
||||||
|
arch/time.md:91 «Формат, зона (TIME-1) и ширина (TIME-2) обязаны»
|
||||||
|
lang/go/db-schema.md:88 «именно там он обязан действительно обращать up»
|
||||||
|
lang/go/logging.md:61 «по TIME-2 так и должно быть»
|
||||||
|
lang/go/logging.md:85 «совпадать они обязаны»
|
||||||
|
lang/go/logging.md:295 «выборка … не должна»
|
||||||
|
```
|
||||||
|
|
||||||
|
Лечение в большинстве случаев — заменить пересказ ссылкой на идентификатор,
|
||||||
|
который в тех же фразах уже стоит рядом.
|
||||||
|
|
||||||
|
Остальные три совпадения отброшены как омонимы: «за попыткой следует повтор»
|
||||||
|
(`logging.md:400`), «становится обязанностью каждого вызывающего» (`db-
|
||||||
|
identifiers.md:42`), «заметить можно, только зная, что они должны были быть»
|
||||||
|
(`logging.md:186`) — все три описывают ход событий, а не требуют. Это и есть
|
||||||
|
причина, по которой META-26 — рекомендация: греп находит слово, а не
|
||||||
|
нарушение.
|
||||||
|
|
||||||
## Мелкое, не закрыто
|
## Мелкое, не закрыто
|
||||||
|
|
||||||
|
|||||||
@@ -163,14 +163,16 @@ dev-выводом перестаёшь ежедневно гонять собс
|
|||||||
|
|
||||||
### SLOG-12. Фатальный сбой на старте — `ERROR` и ненулевой код возврата
|
### SLOG-12. Фатальный сбой на старте — `ERROR` и ненулевой код возврата
|
||||||
|
|
||||||
**ДОЛЖЕН.** `slog` не разделяет CRITICAL/FATAL, поэтому недостающую
|
**ДОЛЖЕН.** Фатальный сбой на старте пишется как `ERROR` и завершает процесс
|
||||||
степень даёт завершение процесса.
|
ненулевым кодом.
|
||||||
|
|
||||||
**Почему.** Супервизор (docker, journald, systemd) отличает падение от
|
**Почему.** `slog` не разделяет CRITICAL и FATAL, поэтому недостающую степень
|
||||||
штатной остановки по коду возврата, а не по уровню последней записи.
|
выражает не уровень записи, а сам факт завершения. Супервизор (docker,
|
||||||
Процесс, который написал `ERROR` и продолжил жить с неработающей
|
journald, systemd) отличает падение от штатной остановки по коду возврата, а
|
||||||
конфигурацией, выглядит здоровым и будет получать трафик; изобретать же
|
не по уровню последней записи. Процесс, который написал `ERROR` и продолжил
|
||||||
уровень выше `ERROR` не нужно — сам факт завершения информативнее.
|
жить с неработающей конфигурацией, выглядит здоровым и будет получать трафик;
|
||||||
|
изобретать же уровень выше `ERROR` не нужно — сам факт завершения
|
||||||
|
информативнее.
|
||||||
|
|
||||||
## Поля: единый словарь
|
## Поля: единый словарь
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user