From 3e0ec461341ed769cef31ab17bf2be5ec09e86fa Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Sun, 26 Jul 2026 14:18:06 +0300 Subject: [PATCH] =?UTF-8?q?guide:=20=D0=B7=D0=B0=D0=B2=D0=B5=D0=B4=D1=91?= =?UTF-8?q?=D0=BD=20META-26=20=E2=80=94=20=D0=BE=D0=B1=D0=BE=D1=81=D0=BD?= =?UTF-8?q?=D0=BE=D0=B2=D0=B0=D0=BD=D0=B8=D0=B5=20=D0=BE=D0=B1=D1=8A=D1=8F?= =?UTF-8?q?=D1=81=D0=BD=D1=8F=D0=B5=D1=82,=20=D0=B0=20=D0=BD=D0=B5=20?= =?UTF-8?q?=D1=82=D1=80=D0=B5=D0=B1=D1=83=D0=B5=D1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - «Почему» не пересказывает норму словами обязательства: у оригинала есть идентификатор, у копии нет, и расходятся они при первой правке оригинала, а отступление от копии адресовать нечем - модальность рекомендательная по META-6: греп находит слово, а не нарушение — «за попыткой следует повтор» и «становится обязанностью вызывающего» описывают ход событий; утверждения о невозможности («нельзя») правилом не затрагиваются, это ISO-евская возможность в прозе - SLOG-12 починен: факт о том, что `slog` не разделяет CRITICAL и FATAL, уехал из нормы в «Почему», а норма теперь говорит то же, что заголовок --- CLAUDE.md | 4 ++++ GUIDE.md | 19 +++++++++++++++++ LANGUAGE.md | 6 +++++- TODO.md | 38 +++++++++++++++++++++++++++------- conventions/lang/go/logging.md | 16 +++++++------- 5 files changed, 67 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 78943ed..c0a7838 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,6 +39,10 @@ code in this repository. Исключение — строка о версии языка, которая их перечисляет. - «Почему» отвечает на «что сломается, если сделать иначе», а не пересказывает норму. «Потому что так принято» — не обоснование. +- META-26: «Почему» не повторяет норму словами обязательства — на неё + ссылаются идентификатором. Утверждения о невозможности (`нельзя`) — факт, а + не запрет, и допустимы. Модальность рекомендательная: греп по `должен`, + `обязан`, `следует` даёт кандидатов, но слова омонимичны. - Служебные слова сценарного блока — тоже словарь набора: **КОГДА**, **ТОГДА**, **И**, **ИЛИ** (по-английски `WHEN`/`THEN`/`AND`/`OR`). Одна форма на роль, заглавными. Модальностью не являются, в строку о версии diff --git a/GUIDE.md b/GUIDE.md index 4c7eb63..9081c28 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -232,6 +232,25 @@ prefix: META существует. Без обоснования не видно, когда причина отпала, — проверка продолжает работать по инерции, и возразить ей нечем, кроме как отключив. +### META-26. Обоснование объясняет, а не требует + +**НЕ СЛЕДУЕТ.** Абзац «Почему» не повторяет норму словами обязательства — на +ту норму, на которую он опирается, ссылаются идентификатором. + +**Почему.** Обоснование, сформулированное как требование, заводит вторую +копию нормы: у оригинала есть идентификатор, у копии нет, и расходятся они +при первой же правке оригинала. Читатель не отличает объяснение от +досказанной нормы, а отступление от копии не адресуемо — ссылаться на абзац +нечем. + +Утверждения о невозможности («нельзя», «не выйдет») сюда не относятся: они +описывают, чего не бывает, а не то, что запрещено, и проза — их законное +место. Модальность здесь рекомендательная не по слабости, а по META-6: +машинная проверка даёт кандидатов, а не вердикт, потому что слова +омонимичны — «за попыткой следует повтор» и «присвоение становится +обязанностью каждого вызывающего» описывают ход событий. Вердикт остаётся за +чтением, грепу достаётся роль подсказки. + ### META-11. У трудноизменяемого слоя область действия пишется явно **ДОЛЖЕН.** Конвенция о схеме БД, формате хранения или раскладке директорий diff --git a/LANGUAGE.md b/LANGUAGE.md index 5c4cf29..295cbe3 100644 --- a/LANGUAGE.md +++ b/LANGUAGE.md @@ -395,4 +395,8 @@ MIGR-6 не соблюдается в легаси-таблицах `show_histor - строки таблицы взаимоисключающи либо политика совпадения объявлена; - перечисленные в таблице случаи покрывают область действия; - норма исполнима без обращения к другим файлам; -- обоснование отвечает на «что сломается», а не пересказывает норму. +- обоснование отвечает на «что сломается», а не пересказывает норму; +- обоснование не повторяет норму словами обязательства (META-26). Кандидатов + находит греп по `должен`, `обязан`, `следует`, `необходимо` в абзацах + «Почему», но вердикт остаётся за чтением: слова омонимичны — «за попыткой + следует повтор» требованием не является. diff --git a/TODO.md b/TODO.md index 047c7bb..dc49733 100644 --- a/TODO.md +++ b/TODO.md @@ -122,16 +122,38 @@ Go-бинарь со своим релизным циклом, ставить ч Работа читательская, машине не даётся; в список проверок она уже записана в разделе «Чтением, потому что машине не даётся». -## 7. Возможность, записанная модальным словом +## 7. Пересказ нормы в «Почему» — вычитать под META-26 -Четвёртая категория ISO — возможность и осуществимость — ключевого слова не -имеет: такие утверждения пишутся обычной прозой. Значит канон надо просмотреть -на обратную ошибку: где утверждение о факте («библиотеки по умолчанию отдают -именно его», «SQLite сравнивает строки побайтово») записано модальным словом -и тем самым превратилось в норму, которую никто не вводил. +Исходный вопрос («где факт записан модальным словом») закрыт по существу: +канон просмотрен, и такой ошибки в нём практически нет. Тринадцать строчных +«нельзя» оказались корректными — это утверждения о невозможности, ISO-евская +возможность в прозе, ровно как задумано. Единственный настоящий случай, +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 — рекомендация: греп находит слово, а не +нарушение. ## Мелкое, не закрыто diff --git a/conventions/lang/go/logging.md b/conventions/lang/go/logging.md index 4684e5b..efd1253 100644 --- a/conventions/lang/go/logging.md +++ b/conventions/lang/go/logging.md @@ -163,14 +163,16 @@ dev-выводом перестаёшь ежедневно гонять собс ### SLOG-12. Фатальный сбой на старте — `ERROR` и ненулевой код возврата -**ДОЛЖЕН.** `slog` не разделяет CRITICAL/FATAL, поэтому недостающую -степень даёт завершение процесса. +**ДОЛЖЕН.** Фатальный сбой на старте пишется как `ERROR` и завершает процесс +ненулевым кодом. -**Почему.** Супервизор (docker, journald, systemd) отличает падение от -штатной остановки по коду возврата, а не по уровню последней записи. -Процесс, который написал `ERROR` и продолжил жить с неработающей -конфигурацией, выглядит здоровым и будет получать трафик; изобретать же -уровень выше `ERROR` не нужно — сам факт завершения информативнее. +**Почему.** `slog` не разделяет CRITICAL и FATAL, поэтому недостающую степень +выражает не уровень записи, а сам факт завершения. Супервизор (docker, +journald, systemd) отличает падение от штатной остановки по коду возврата, а +не по уровню последней записи. Процесс, который написал `ERROR` и продолжил +жить с неработающей конфигурацией, выглядит здоровым и будет получать трафик; +изобретать же уровень выше `ERROR` не нужно — сам факт завершения +информативнее. ## Поля: единый словарь