ПОЧЕМУ стало ключевым словом, язык поднят до версии 2
- метка обоснования пишется заглавными и вошла в словарь набора: скелет правила теперь целиком из ключевых слов, а не смесь `**ДОЛЖЕН.**` и `**Почему.**`; в переводе на другой язык метка меняется как остальные слова (ПОЧЕМУ / WHY), 235 вхождений заменены - метки правила выделены из шкалы в отдельный перечень: ПОЧЕМУ и МЕХАНИЗИРОВАНО обязательности не задают, а размечают части, и стандартом не даются ни в одном языке — раньше МЕХАНИЗИРОВАНО висело строкой в таблице модальности - версия языка поднята до 2, потому что изменение формы меняет чтение уже написанного текста; строка о версии в двенадцати конвенциях перечисляет теперь и метки, а служебные слова сценария в неё по-прежнему не входят
This commit is contained in:
@@ -62,7 +62,7 @@ prefix: META
|
||||
|
||||
**ДОЛЖЕН.** Файл описывает ровно один повторяющийся выбор.
|
||||
|
||||
**Почему.** Подписка перечисляется по темам, и тему берут целиком. Файл,
|
||||
**ПОЧЕМУ.** Подписка перечисляется по темам, и тему берут целиком. Файл,
|
||||
собравший две темы, вынуждает репозиторий взять правила, которые ему не
|
||||
нужны, и вычитывать чужую половину при каждом обновлении. Разрезать позже
|
||||
дорого: перенос правила в другой файл — это новый префикс и новая
|
||||
@@ -73,7 +73,7 @@ prefix: META
|
||||
**СЛЕДУЕТ.** Поводом служит одно и то же решение, принятое третий раз и
|
||||
каждый раз чуть по-другому.
|
||||
|
||||
**Почему.** По одному-двум случаям не видно, что в решении повторяется, а
|
||||
**ПОЧЕМУ.** По одному-двум случаям не видно, что в решении повторяется, а
|
||||
что было частностью места: правило, выведенное из первого случая, кодирует
|
||||
частность и дальше мешает больше, чем помогает. Единичный выбор, к тому же
|
||||
спорный, читателю нужен вместе с мотивом — это ADR, где мотив и есть
|
||||
@@ -85,7 +85,7 @@ prefix: META
|
||||
удаление прозы» делаются в репозитории, где случилась находка; в канон
|
||||
продвигается общая часть.
|
||||
|
||||
**Почему.** Правило, написанное сразу в общем виде, не проверено ни одним
|
||||
**ПОЧЕМУ.** Правило, написанное сразу в общем виде, не проверено ни одним
|
||||
применением, и условие применимости у него придумано, а не найдено, —
|
||||
платят за это все потребители сразу. Формулировка, обкатанная на одном
|
||||
репозитории, приезжает в канон уже с известной границей.
|
||||
@@ -95,7 +95,7 @@ prefix: META
|
||||
**НЕ ДОЛЖЕН.** Норма пишется в настоящем предписывающем времени, без
|
||||
описаний того, как сейчас устроен конкретный репозиторий.
|
||||
|
||||
**Почему.** Такое утверждение устаревает молча и подменяет норму описанием:
|
||||
**ПОЧЕМУ.** Такое утверждение устаревает молча и подменяет норму описанием:
|
||||
читатель перестаёт понимать, что от него требуется, а что просто
|
||||
констатировано. В копиях у остальных потребителей чужой факт вдобавок ложен
|
||||
с первого дня. «Так сделано у нас» — содержимое региона отступлений, где оно
|
||||
@@ -104,12 +104,12 @@ prefix: META
|
||||
### META-20. Норма самодостаточна, наружу смотрит только обоснование
|
||||
|
||||
**ДОЛЖЕН.** Норму правила можно исполнить, имея один этот файл. Ссылка на
|
||||
правило чужой темы допустима в «Почему», в «Связано» и в разграничении
|
||||
правило чужой темы допустима в обосновании, в «Связано» и в разграничении
|
||||
области действия — но не в самой норме. Если норме нужен концепт соседней
|
||||
темы, он коротко повторяется здесь, а сосед называется в «Почему» как
|
||||
темы, он коротко повторяется здесь, а сосед называется в обосновании как
|
||||
источник решения.
|
||||
|
||||
**Почему.** Репозиторий подписывается на произвольное подмножество
|
||||
**ПОЧЕМУ.** Репозиторий подписывается на произвольное подмножество
|
||||
конвенций, и графа зависимостей у него нет по построению. Норма, которую
|
||||
нельзя исполнить без отсутствующего файла, делает такое подмножество
|
||||
невалидным молча: читатель видит связный текст и не замечает, что часть
|
||||
@@ -124,7 +124,7 @@ prefix: META
|
||||
`logging`), на конкретное правило — идентификатором (`SLOG-27`); путь файла
|
||||
канона в тексте конвенции не употребляется.
|
||||
|
||||
**Почему.** В репозитории конвенция лежит собранной: слои одной темы — это
|
||||
**ПОЧЕМУ.** В репозитории конвенция лежит собранной: слои одной темы — это
|
||||
секции одного файла, и пути `lang/go/logging.md` там не существует. Ссылка
|
||||
на путь канона умирает при сборке, причём молча — текст остаётся связным.
|
||||
Имя темы и идентификатор правила переживают и сборку, и переезд файла между
|
||||
@@ -136,7 +136,7 @@ prefix: META
|
||||
**ДОПУСКАЕТСЯ.** Правило языкового или стекового слоя называет идентификатор
|
||||
правила арх-слоя своей темы прямо в норме.
|
||||
|
||||
**Почему.** Подписываются темой, а не слоем: собранный файл начинается с
|
||||
**ПОЧЕМУ.** Подписываются темой, а не слоем: собранный файл начинается с
|
||||
арх-слоя независимо от того, какие язык и стек выбраны, — базовое правило в
|
||||
копии всегда рядом, и ссылка на него никуда не ведёт. Повтор его концепта
|
||||
здесь заводил бы второй источник правды внутри одного документа: META-20
|
||||
@@ -152,7 +152,7 @@ prefix: META
|
||||
фактическую ошибку, внутреннее противоречие или условие применимости,
|
||||
которое не даёт ответа.
|
||||
|
||||
**Почему.** Правило, подогнанное под текущий код, перестаёт что-либо
|
||||
**ПОЧЕМУ.** Правило, подогнанное под текущий код, перестаёт что-либо
|
||||
требовать — оно описывает то, что и так происходит, и первое же расхождение
|
||||
переписывает его снова. Направление «конвенция → код» держится ровно тем,
|
||||
что факт не считается аргументом.
|
||||
@@ -162,7 +162,7 @@ prefix: META
|
||||
**ДОЛЖЕН.** Правило, нарушение которого объявлено ошибкой, получает
|
||||
машинную проверку или переводится в СЛЕДУЕТ.
|
||||
|
||||
**Почему.** Без проверки правило держится на внимании: нарушения копятся
|
||||
**ПОЧЕМУ.** Без проверки правило держится на внимании: нарушения копятся
|
||||
молча и всплывают выборочно — на том ревью, куда дошли руки. Для СЛЕДУЕТ
|
||||
это честно, а ДОЛЖЕН при этом обещает то, чего не делает, и через несколько
|
||||
таких случаев обесценивает остальные ДОЛЖЕН в файле.
|
||||
@@ -173,10 +173,10 @@ prefix: META
|
||||
|
||||
### META-25. Высшая модальность выбирается, только когда назван вред
|
||||
|
||||
**СЛЕДУЕТ.** Правило получает ДОЛЖЕН или НЕ ДОЛЖЕН, если в «Почему» сказано,
|
||||
что́ ломается при нарушении.
|
||||
**СЛЕДУЕТ.** Правило получает ДОЛЖЕН или НЕ ДОЛЖЕН, если в обосновании
|
||||
сказано, что́ ломается при нарушении.
|
||||
|
||||
**Почему.** Машинная проверка — условие необходимое (META-6), но не
|
||||
**ПОЧЕМУ.** Машинная проверка — условие необходимое (META-6), но не
|
||||
достаточное: проверяемых мелочей больше, чем важных вещей, и без второго
|
||||
условия единственным фильтром остаётся удобство проверки. Шкала наполняется
|
||||
опрятностью, читатель перестаёт отличать «уронит прод» от «неаккуратно» — и
|
||||
@@ -190,7 +190,7 @@ prefix: META
|
||||
**ДОЛЖЕН.** Запись о механизации называет идентификатор правила и
|
||||
конкретную проверку.
|
||||
|
||||
**Почему.** Механизация — состояние конкретного репозитория, канон о ней не
|
||||
**ПОЧЕМУ.** Механизация — состояние конкретного репозитория, канон о ней не
|
||||
знает, а без записи следующий автор либо заведёт вторую проверку того же,
|
||||
либо будет вычитывать глазами уже проверенное машиной. Без идентификатора
|
||||
читатель догадывается сам, к какому утверждению относится проверка, — и
|
||||
@@ -201,7 +201,7 @@ prefix: META
|
||||
**НЕ ДОЛЖЕН.** Норма остаётся в каноне, пока хотя бы у одного потребителя
|
||||
машинной проверки нет.
|
||||
|
||||
**Почему.** У кого линтера нет, тот после удаления остаётся без правила
|
||||
**ПОЧЕМУ.** У кого линтера нет, тот после удаления остаётся без правила
|
||||
вообще: ни проверки, ни текста. Механизация у одного потребителя ничего не
|
||||
говорит о прочих, поэтому удалять по факту «у нас уже проверяется» —
|
||||
значит чинить свой файл за чужой счёт.
|
||||
@@ -216,7 +216,7 @@ prefix: META
|
||||
**ДОПУСКАЕТСЯ.** Правило, уехавшее в общий конфиг линтера или в общую роль,
|
||||
удаляется из канона.
|
||||
|
||||
**Почему.** Формулировка, дублирующая работающую у всех проверку,
|
||||
**ПОЧЕМУ.** Формулировка, дублирующая работающую у всех проверку,
|
||||
размазывает внимание: файл на несколько сотен строк заставляет человека и
|
||||
агента добросовестно вычитывать тривиальное именование и не доходить до
|
||||
формы решения. Явное разрешение нужно, чтобы META-8 не читался как запрет
|
||||
@@ -224,10 +224,10 @@ prefix: META
|
||||
|
||||
### META-10. Обоснование не удаляется никогда
|
||||
|
||||
**НЕ ДОЛЖЕН.** Блок «Почему» остаётся и после того, как норма уехала в
|
||||
**НЕ ДОЛЖЕН.** Блок ПОЧЕМУ остаётся и после того, как норма уехала в
|
||||
линтер.
|
||||
|
||||
**Почему.** Линтер сообщает, что нарушено, но не сообщает, зачем правило
|
||||
**ПОЧЕМУ.** Линтер сообщает, что нарушено, но не сообщает, зачем правило
|
||||
существует. Без обоснования не видно, когда причина отпала, — проверка
|
||||
продолжает работать по инерции, и возразить ей нечем, кроме как отключив.
|
||||
|
||||
@@ -237,7 +237,7 @@ prefix: META
|
||||
называет, к чему применяется: к новым таблицам и миграциям, а не к
|
||||
состоянию схемы.
|
||||
|
||||
**Почему.** Здесь не работает привычное «новое пишем правильно, старое
|
||||
**ПОЧЕМУ.** Здесь не работает привычное «новое пишем правильно, старое
|
||||
переезжает по мере касания»: таблица не переезжает от того, что её
|
||||
потрогали. Без явной рамки правило читается как требование к текущему
|
||||
состоянию, и оба исхода плохи — миграция живых данных ради опрятности либо
|
||||
@@ -248,7 +248,7 @@ prefix: META
|
||||
**ДОЛЖЕН.** Проверка запрещает нарушение в новых миграциях, а не в уже
|
||||
существующей схеме.
|
||||
|
||||
**Почему.** Проверка состояния краснеет на легаси с первого дня: её
|
||||
**ПОЧЕМУ.** Проверка состояния краснеет на легаси с первого дня: её
|
||||
отключают или обвешивают вечным списком исключений — и она перестаёт ловить
|
||||
новое, ради чего заводилась. Проверка границы оставляет старое в покое и
|
||||
делает новую ошибку невозможной.
|
||||
@@ -258,7 +258,7 @@ prefix: META
|
||||
**ДОЛЖЕН.** Перечисленные старые таблицы и раскладки живут как есть, а не
|
||||
как задачи на дочистку.
|
||||
|
||||
**Почему.** Список, записанный долгом, требует либо мигрировать живые данные
|
||||
**ПОЧЕМУ.** Список, записанный долгом, требует либо мигрировать живые данные
|
||||
без выгоды, либо год за годом объяснять невыполненный план. Второе кончается
|
||||
тем, что список перестают вести, — и пропадает единственное место, где видно,
|
||||
где именно правило не действует.
|
||||
@@ -268,7 +268,7 @@ prefix: META
|
||||
**ДОЛЖЕН.** В локальной части копии перечислены отступления, которые уже
|
||||
есть в коде, с идентификатором правила и причиной.
|
||||
|
||||
**Почему.** Иначе репозиторий выглядит соблюдающим конвенцию, а проверить
|
||||
**ПОЧЕМУ.** Иначе репозиторий выглядит соблюдающим конвенцию, а проверить
|
||||
это можно только чтением всего кода. Со ссылками отступления счётны: видно,
|
||||
сколько правил конвенции репозиторий реально не соблюдает. Пустой список при
|
||||
этом почти всегда означает не отсутствие отступлений, а то, что их не искали.
|
||||
@@ -283,7 +283,7 @@ prefix: META
|
||||
| META-15.2 | правило не применяется в репозитории целиком | чинится условие применимости — в каноне |
|
||||
| META-15.3 | конвенция репозиторию не нужна | копия удаляется, подписки нет |
|
||||
|
||||
**Почему.** Отступление описывает исключение, и по нему видно, какая часть
|
||||
**ПОЧЕМУ.** Отступление описывает исключение, и по нему видно, какая часть
|
||||
правила нарушена. Запись «мы это правило вообще не применяем» такой
|
||||
информации не несёт и маскирует одну из двух чинимых причин: неверную рамку
|
||||
правила в каноне, которую чинят один раз для всех, или лишнюю подписку,
|
||||
@@ -295,7 +295,7 @@ prefix: META
|
||||
потребителей; ссылки на ADR, код и файлы конкретного репозитория — в
|
||||
локальной части копии.
|
||||
|
||||
**Почему.** Текст канона приезжает ко всем потребителям, и ссылка на чужой
|
||||
**ПОЧЕМУ.** Текст канона приезжает ко всем потребителям, и ссылка на чужой
|
||||
файл у них битая с первого дня. Ниже маркера та же ссылка никого не
|
||||
задевает и переживает обновление, потому что обновление её не трогает.
|
||||
|
||||
@@ -304,7 +304,7 @@ prefix: META
|
||||
**ДОЛЖЕН.** Правки репозитория вносятся ниже маркера, а не в текст,
|
||||
пришедший из канона.
|
||||
|
||||
**Почему.** Обновление перезаписывает всё, что выше маркера, поэтому правка
|
||||
**ПОЧЕМУ.** Обновление перезаписывает всё, что выше маркера, поэтому правка
|
||||
там живёт до первого `pull`. Заметить пропажу можно, только вычитав
|
||||
`git diff` целиком — а он в этот момент и без того полон изменений канона,
|
||||
и своя строка теряется среди чужих.
|
||||
@@ -314,7 +314,7 @@ prefix: META
|
||||
**НЕ ДОЛЖЕН.** Файл, который развели с каноном намеренно, шапку `origin:`
|
||||
не сохраняет.
|
||||
|
||||
**Почему.** По `origin:` решается, какие файлы пересобирать из канона. Форк,
|
||||
**ПОЧЕМУ.** По `origin:` решается, какие файлы пересобирать из канона. Форк,
|
||||
оставивший шапку, при первом же обновлении теряет ровно то, ради чего его
|
||||
заводили. Происхождение такого документа остаётся в истории коммита, где оно
|
||||
никого не вводит в заблуждение.
|
||||
@@ -323,7 +323,7 @@ prefix: META
|
||||
|
||||
**СЛЕДУЕТ.** Одна плоская таблица: файл и строка о том, про что он.
|
||||
|
||||
**Почему.** Подписка — это набор лежащих файлов, и без описаний вопрос
|
||||
**ПОЧЕМУ.** Подписка — это набор лежащих файлов, и без описаний вопрос
|
||||
«какая из них про мой случай» решается открыванием каждой. Ценой в десяток
|
||||
файлов это означает, что не открывают ни одной.
|
||||
|
||||
@@ -332,7 +332,7 @@ prefix: META
|
||||
**ДОЛЖЕН.** В `AGENTS.md` / `CLAUDE.md` едет одна строка на правило с его
|
||||
идентификатором; детали остаются в конвенции.
|
||||
|
||||
**Почему.** Сама по себе конвенция агенту не видна: он дойдёт до неё, только
|
||||
**ПОЧЕМУ.** Сама по себе конвенция агенту не видна: он дойдёт до неё, только
|
||||
если его туда отправили, — а безусловно он читает точку входа. Строка с
|
||||
идентификатором служит и напоминанием, и адресом, по которому за
|
||||
подробностями идут; перенос деталей туда же вернул бы задачу поддержки двух
|
||||
@@ -347,4 +347,4 @@ prefix: META
|
||||
| Номер | Что было | Почему снято |
|
||||
|---|---|---|
|
||||
| META-16 | имя файла — kebab-case | вреда от нарушения нет (META-25); осталось прозой в «Оформлении» |
|
||||
| META-26 | запрет слов обязательства в «Почему» | правило о заглавных уже делает строчное слово ненормативным, а форму обоснования рамками не ограничивают |
|
||||
| META-26 | запрет слов обязательства в обосновании | правило о заглавных уже делает строчное слово ненормативным, а форму обоснования рамками не ограничивают |
|
||||
|
||||
Reference in New Issue
Block a user