ПОЧЕМУ стало ключевым словом, язык поднят до версии 2
- метка обоснования пишется заглавными и вошла в словарь набора: скелет правила теперь целиком из ключевых слов, а не смесь `**ДОЛЖЕН.**` и `**Почему.**`; в переводе на другой язык метка меняется как остальные слова (ПОЧЕМУ / WHY), 235 вхождений заменены - метки правила выделены из шкалы в отдельный перечень: ПОЧЕМУ и МЕХАНИЗИРОВАНО обязательности не задают, а размечают части, и стандартом не даются ни в одном языке — раньше МЕХАНИЗИРОВАНО висело строкой в таблице модальности - версия языка поднята до 2, потому что изменение формы меняет чтение уже написанного текста; строка о версии в двенадцати конвенциях перечисляет теперь и метки, а служебные слова сценария в неё по-прежнему не входят
This commit is contained in:
+59
-34
@@ -1,5 +1,5 @@
|
||||
---
|
||||
version: 1
|
||||
version: 2
|
||||
---
|
||||
|
||||
# Язык конвенций
|
||||
@@ -8,7 +8,7 @@ version: 1
|
||||
правилом, чем оно отличается от прозы вокруг, какими словами задаётся
|
||||
обязательность и как на правило сослаться извне.
|
||||
|
||||
Версия языка — **1**. Номер называется в каждой конвенции: словарь может
|
||||
Версия языка — **2**. Номер называется в каждой конвенции: словарь может
|
||||
пополниться, и текст, написанный по предыдущей версии, должен читаться по
|
||||
той, по которой написан.
|
||||
|
||||
@@ -77,20 +77,24 @@ version: 1
|
||||
**ДОЛЖЕН.** Идентификатор, пришедший снаружи, проходит разбор до запроса
|
||||
к базе.
|
||||
|
||||
**Почему.** Разбор валидирует формат и нормализует регистр. Сравнение строк
|
||||
**ПОЧЕМУ.** Разбор валидирует формат и нормализует регистр. Сравнение строк
|
||||
в базе побайтовое, поэтому без нормализации запрос молча не находит
|
||||
существующую запись — отладка такого случая стоит дороже, чем сам разбор.
|
||||
```
|
||||
|
||||
Четыре обязательные части: **идентификатор**, **заголовок**, **модальность
|
||||
с нормой**, **обоснование**. Норма — одна фраза; если в неё не влезает, это
|
||||
два правила. Требование единичности взято из ISO/IEC/IEEE 29148: составная
|
||||
норма не проверяема целиком, и нарушение одной её половины нечем
|
||||
адресовать.
|
||||
с нормой**, **обоснование под меткой ПОЧЕМУ**. Норма — одна фраза; если в неё
|
||||
не влезает, это два правила. Требование единичности взято из ISO/IEC/IEEE
|
||||
29148: составная норма не проверяема целиком, и нарушение одной её половины
|
||||
нечем адресовать.
|
||||
|
||||
Обе метки правила — модальное слово и ПОЧЕМУ — пишутся заглавными и
|
||||
принадлежат словарю набора: скелет правила читается одинаково в любом языке,
|
||||
на который канон переведён.
|
||||
|
||||
## Обоснование обязательно
|
||||
|
||||
Правило без блока «Почему» не принимается. Это требование к форме, а не
|
||||
Правило без блока ПОЧЕМУ не принимается. Это требование к форме, а не
|
||||
пожелание; в 29148 обоснование — атрибут требования наравне с самим
|
||||
требованием, и по тем же причинам:
|
||||
|
||||
@@ -104,8 +108,9 @@ version: 1
|
||||
Если причина не формулируется, перед нами привычка или вкусовщина; ей
|
||||
место в черновиках, а не в конвенции.
|
||||
|
||||
«Почему» отвечает на «что сломается, если сделать иначе», а не пересказывает
|
||||
норму другими словами. «Потому что так принято» — не обоснование.
|
||||
Обоснование отвечает на «что сломается, если сделать иначе», а не
|
||||
пересказывает норму другими словами. «Потому что так принято» — не
|
||||
обоснование.
|
||||
|
||||
Форма обоснования при этом ничем не ограничена: рамки здесь только
|
||||
смысловые. Абзац может быть длинным, вести рассуждение, приводить пример,
|
||||
@@ -172,14 +177,12 @@ Directives, Part 2, по одной форме записи на ступень,
|
||||
|
||||
## Словарь другого языка
|
||||
|
||||
Словарь набора — это два перечня: модальные слова и служебные слова
|
||||
сценарного блока (`КОГДА`, `ТОГДА`, `И`, `ИЛИ` — см. «Таблицы решений»).
|
||||
Требования к ним одни и те же.
|
||||
Словарь набора — три перечня, и требования к ним одни и те же.
|
||||
|
||||
Для английского готовый словарь модальных слов даёт BCP 14. Для любого
|
||||
другого языка слова берут из перевода стандарта, если он есть, или переводят
|
||||
сами: шкала и семантика ступеней при этом не меняются — меняется только
|
||||
запись.
|
||||
**Шкала обязательности.** Для английского готовый словарь даёт BCP 14; для
|
||||
любого другого языка слова берут из перевода стандарта, если он есть, или
|
||||
переводят сами. Шкала и семантика ступеней при этом не меняются — меняется
|
||||
только запись.
|
||||
|
||||
| Ступень | Русский | Английский (BCP 14) |
|
||||
|---|---|---|
|
||||
@@ -188,22 +191,32 @@ Directives, Part 2, по одной форме записи на ступень,
|
||||
| рекомендация | СЛЕДУЕТ | SHOULD |
|
||||
| рекомендация против | НЕ СЛЕДУЕТ | SHOULD NOT |
|
||||
| разрешение | ДОПУСКАЕТСЯ | MAY |
|
||||
| отметка о способе проверки | МЕХАНИЗИРОВАНО | MECHANIZED |
|
||||
|
||||
Последняя строка стандартом не даётся ни в одном языке: способа проверки в
|
||||
шкале BCP 14 нет, слово подбирается под язык так же, как остальные.
|
||||
**Метки правила.** Обязательности не задают, а размечают его части.
|
||||
Стандартом не даются ни в одном языке: в BCP 14 таких понятий нет, слова
|
||||
подбираются под язык так же, как остальные.
|
||||
|
||||
| Метка | Русский | Английский |
|
||||
|---|---|---|
|
||||
| обоснование | ПОЧЕМУ | WHY |
|
||||
| способ проверки | МЕХАНИЗИРОВАНО | MECHANIZED |
|
||||
|
||||
**Служебные слова сценарного блока** — `КОГДА`, `ТОГДА`, `И`, `ИЛИ`; таблица
|
||||
и объяснение в разделе «Таблицы решений».
|
||||
|
||||
Что требуется от любого словаря:
|
||||
|
||||
- **одна форма на ступень.** Синонимы отклонены не из аскетизма: проверка
|
||||
«модальное слово вне правила» перечисляет формы, и синонимический ряд
|
||||
превращает перечисление в разбор.
|
||||
- **одна форма на ступень и на метку.** Синонимы отклонены не из аскетизма:
|
||||
проверка «модальное слово вне правила» перечисляет формы, и синонимический
|
||||
ряд превращает перечисление в разбор.
|
||||
- **слово заглавными не встречается в обычной прозе этого языка.** Иначе
|
||||
правило «нормативно только заглавное» перестаёт спасать: проверка ловит
|
||||
оформление, а не модальность.
|
||||
- **словарь перечислен целиком в строке о версии языка.** Читателю копии он
|
||||
известен из самого файла, без обращения к этому документу, — иначе
|
||||
конвенция в чужом репозитории теряет ключ к собственному тексту.
|
||||
- **модальные слова и метки перечислены в строке о версии языка.** Читателю
|
||||
копии они известны из самого файла, без обращения к этому документу, —
|
||||
иначе конвенция в чужом репозитории теряет ключ к собственному тексту.
|
||||
Служебные слова сценария в строку не входят: структура блока читается из
|
||||
самого блока, и в файле без стыков правил их нет вовсе.
|
||||
- **словарь один на канон.** Два словаря параллельно дают две формы записи
|
||||
одного требования и удваивают каждую проверку; выбор языка — свойство
|
||||
набора, а не отдельного файла.
|
||||
@@ -215,16 +228,16 @@ Directives, Part 2, по одной форме записи на ступень,
|
||||
|
||||
Каждая конвенция называет язык одной строкой во вводной прозе:
|
||||
|
||||
> Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и
|
||||
> отметка МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 —
|
||||
> Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
|
||||
> ПОЧЕМУ и МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 2 —
|
||||
> тогда и только тогда, когда написаны заглавными.
|
||||
|
||||
Слова в строке — из словаря того языка, на котором написан набор. Для
|
||||
англоязычного набора та же строка выглядит так:
|
||||
|
||||
> The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and the mark
|
||||
> MECHANIZED are to be interpreted as described in the conventions language,
|
||||
> version 1, and only when written in capitals.
|
||||
> The key words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and the marks WHY
|
||||
> and MECHANIZED are to be interpreted as described in the conventions
|
||||
> language, version 2, and only when written in capitals.
|
||||
|
||||
Форма скопирована у BCP 14, где та же задача решается тем же способом:
|
||||
спецификация не прикладывает к себе словарь и не указывает путь к нему, а
|
||||
@@ -248,14 +261,14 @@ Directives, Part 2, по одной форме записи на ступень,
|
||||
**ДОЛЖЕН. МЕХАНИЗИРОВАНО.** Проверяется общим правилом линтера;
|
||||
формулировка удалена, потому что дублировала работающую проверку.
|
||||
|
||||
**Почему.** Дефолт превращает забытую вставку в тихо работающий код…
|
||||
**ПОЧЕМУ.** Дефолт превращает забытую вставку в тихо работающий код…
|
||||
```
|
||||
|
||||
- Идентификатор и заголовок сохраняются: ссылки из репозиториев продолжают
|
||||
указывать на то же утверждение.
|
||||
- Модальность сохраняется, поэтому «все ли ДОЛЖЕН механизированы»
|
||||
остаётся вычислимым вопросом, а не предметом чтения всего канона.
|
||||
- «Почему» остаётся навсегда — линтер сообщает, что нарушено, но не
|
||||
- Обоснование остаётся навсегда — линтер сообщает, что нарушено, но не
|
||||
сообщает, зачем правило существует, и без обоснования нельзя понять,
|
||||
когда проверку пора отменять.
|
||||
|
||||
@@ -386,7 +399,7 @@ MIGR-6 не соблюдается в легаси-таблицах `show_histor
|
||||
- заголовки правил файла используют только его собственный префикс;
|
||||
- номера уникальны внутри файла и не имеют пропусков вниз (новое правило
|
||||
берёт следующий свободный, а не первый освободившийся);
|
||||
- у каждого `### <ПРЕФИКС>-<n>` есть модальное слово и блок «Почему»;
|
||||
- у каждого `### <ПРЕФИКС>-<n>` есть модальное слово и блок ПОЧЕМУ;
|
||||
отметка МЕХАНИЗИРОВАНО стоит рядом с модальностью, а не вместо неё;
|
||||
- вводная проза содержит строку о версии языка;
|
||||
- ссылки вида `<ПРЕФИКС>-<n>` — хоть в тексте канона, хоть в локальной части
|
||||
@@ -405,3 +418,15 @@ MIGR-6 не соблюдается в легаси-таблицах `show_histor
|
||||
- перечисленные в таблице случаи покрывают область действия;
|
||||
- норма исполнима без обращения к другим файлам;
|
||||
- обоснование отвечает на «что сломается», а не пересказывает норму.
|
||||
|
||||
## История версий
|
||||
|
||||
Номер версии называется в каждой конвенции, поэтому изменение формы, способное
|
||||
изменить чтение уже написанного текста, меняет и номер. Смена словаря под
|
||||
другой естественный язык версию не двигает: версия принадлежит шкале, меткам и
|
||||
правилам формы, а не буквам.
|
||||
|
||||
| Версия | Что изменилось |
|
||||
|---|---|
|
||||
| 1 | первая запись языка: шкала из BCP 14, обязательное обоснование, идентификаторы, таблицы решений |
|
||||
| 2 | обоснование получило метку ПОЧЕМУ заглавными и вошло в словарь набора; метки правила выделены из шкалы в отдельный перечень |
|
||||
|
||||
Reference in New Issue
Block a user