ПОЧЕМУ стало ключевым словом, язык поднят до версии 2
- метка обоснования пишется заглавными и вошла в словарь набора: скелет правила теперь целиком из ключевых слов, а не смесь `**ДОЛЖЕН.**` и `**Почему.**`; в переводе на другой язык метка меняется как остальные слова (ПОЧЕМУ / WHY), 235 вхождений заменены - метки правила выделены из шкалы в отдельный перечень: ПОЧЕМУ и МЕХАНИЗИРОВАНО обязательности не задают, а размечают части, и стандартом не даются ни в одном языке — раньше МЕХАНИЗИРОВАНО висело строкой в таблице модальности - версия языка поднята до 2, потому что изменение формы меняет чтение уже написанного текста; строка о версии в двенадцати конвенциях перечисляет теперь и метки, а служебные слова сценария в неё по-прежнему не входят
This commit is contained in:
+16
-16
@@ -7,9 +7,9 @@ prefix: TIME
|
||||
Как приложение записывает моменты и длительности: в каком формате, откуда
|
||||
берётся значение и где появляется не-UTC.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
|
||||
ПОЧЕМУ и МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 2 —
|
||||
тогда и только тогда, когда написаны заглавными.
|
||||
|
||||
## Область действия
|
||||
|
||||
@@ -26,7 +26,7 @@ prefix: TIME
|
||||
**ДОЛЖЕН.** Момент времени записывается как `2026-06-28T11:23:45Z` —
|
||||
одинаково в хранении, логах, API и обмене с внешними системами.
|
||||
|
||||
**Почему.** Разные форматы в разных слоях требуют преобразования на каждой
|
||||
**ПОЧЕМУ.** Разные форматы в разных слоях требуют преобразования на каждой
|
||||
границе, а ошибка в таком преобразовании не видна сразу: она всплывает через
|
||||
полгода, на переходе на летнее время, когда реальное смещение перестаёт
|
||||
совпадать с тем, которое подразумевалось при написании кода. UTC с явным `Z`
|
||||
@@ -37,7 +37,7 @@ prefix: TIME
|
||||
**ДОЛЖЕН.** Внутри одной колонки БД и внутри одного потока логов длина
|
||||
строки времени одна и от записи к записи не плавает.
|
||||
|
||||
**Почему.** Лексикографическая сортировка совпадает с хронологией только
|
||||
**ПОЧЕМУ.** Лексикографическая сортировка совпадает с хронологией только
|
||||
среди строк одинаковой длины: `…00.123Z` сортируется раньше `…00.12Z`, хотя
|
||||
произошло позже. Ради этого ширина и фиксируется — `ORDER BY created_at` по
|
||||
текстовому полю обязан давать порядок событий. Плавающая ширина (типичный
|
||||
@@ -49,7 +49,7 @@ prefix: TIME
|
||||
|
||||
**ДОПУСКАЕТСЯ.** У колонки БД и у потока логов каждая своя точность.
|
||||
|
||||
**Почему.** Квантор в TIME-2 — на носитель, а не на приложение, потому что
|
||||
**ПОЧЕМУ.** Квантор в TIME-2 — на носитель, а не на приложение, потому что
|
||||
строки разных носителей между собой не сравниваются: сортировка идёт внутри
|
||||
колонки, чтение — внутри потока. Явное разрешение нужно, чтобы TIME-2 не читался
|
||||
как «одна точность на всё приложение»: от подгонки формата логов под формат
|
||||
@@ -61,7 +61,7 @@ prefix: TIME
|
||||
**НЕ ДОЛЖЕН.** Ни в базе, ни в логах, ни в JSON API нет меток в локальной
|
||||
зоне.
|
||||
|
||||
**Почему.** Метка без зоны неинтерпретируема вне процесса, который её
|
||||
**ПОЧЕМУ.** Метка без зоны неинтерпретируема вне процесса, который её
|
||||
записал: чтобы понять, какому моменту она соответствует, читателю нужно
|
||||
знать настройки чужой машины на момент записи. И даже зная их, он не
|
||||
разберёт час перехода на зимнее время: этот час идёт дважды, две записи
|
||||
@@ -73,7 +73,7 @@ prefix: TIME
|
||||
долями секунды принимается от внешней системы и приводится к каноническому
|
||||
виду (TIME-1) в точке разбора (TIME-5).
|
||||
|
||||
**Почему.** Канонический вид — обязательство нашего писателя, а не
|
||||
**ПОЧЕМУ.** Канонический вид — обязательство нашего писателя, а не
|
||||
контракт, наложенный на внешние системы: `…14:23:45+03:00` называет тот же
|
||||
момент, что `…11:23:45Z`, и отклонять его — значит ломать интеграцию со
|
||||
стороной, которая стандарт соблюла. Пропущенное же как есть, такое значение
|
||||
@@ -88,7 +88,7 @@ prefix: TIME
|
||||
**ДОЛЖЕН.** Один модуль отдаёт текущий момент, он же форматирует и разбирает
|
||||
метки; прямые вызовы часов по коду не разбросаны.
|
||||
|
||||
**Почему.** Формат, зона (TIME-1) и ширина (TIME-2) обязаны выполняться для всех
|
||||
**ПОЧЕМУ.** Формат, зона (TIME-1) и ширина (TIME-2) обязаны выполняться для всех
|
||||
меток без исключения, а каждый прямой вызов часов заводит ещё одно место,
|
||||
где их можно не соблюсти. Промах такого вызова проявляется не в коде, а в
|
||||
данных, и обнаруживается, когда испорченных записей уже накопилось.
|
||||
@@ -98,7 +98,7 @@ prefix: TIME
|
||||
|
||||
**НЕ ДОЛЖЕН.** Колонки времени не имеют `DEFAULT` с текущим моментом.
|
||||
|
||||
**Почему.** Дефолт превращает забытую вставку `created_at` в тихо работающий
|
||||
**ПОЧЕМУ.** Дефолт превращает забытую вставку `created_at` в тихо работающий
|
||||
код: значение появляется, но приходит от сервера БД — то есть с других часов
|
||||
и в формате, который выбирала не единая точка (TIME-5). Без дефолта та же ошибка
|
||||
падает громко и чинится в момент написания, а не при разборе расхождения
|
||||
@@ -110,7 +110,7 @@ prefix: TIME
|
||||
**ДОЛЖЕН.** Длительность операции записывается числом (обычно
|
||||
миллисекундами) в поле вида `duration_ms`.
|
||||
|
||||
**Почему.** Метка отвечает на вопрос «когда», длительность — на «сколько».
|
||||
**ПОЧЕМУ.** Метка отвечает на вопрос «когда», длительность — на «сколько».
|
||||
Пара меток заставляет каждого потребителя знать, какие именно две из них
|
||||
образуют операцию, и вычитать их самому — в запросе, в дашборде и глазами в
|
||||
логе; число сравнивается, агрегируется и попадает в перцентили без этого
|
||||
@@ -121,7 +121,7 @@ prefix: TIME
|
||||
|
||||
**СЛЕДУЕТ.** Замер живёт там же, где вызов, границы которого он измеряет.
|
||||
|
||||
**Почему.** Обе границы операции видит только этот слой: замер уровнем выше
|
||||
**ПОЧЕМУ.** Обе границы операции видит только этот слой: замер уровнем выше
|
||||
приписывает операции чужие накладные расходы, уровнем ниже — теряет часть
|
||||
вызова. В обоих случаях число остаётся правдоподобным и потому не
|
||||
оспаривается, хотя отвечает не на тот вопрос, который к нему задают.
|
||||
@@ -135,7 +135,7 @@ prefix: TIME
|
||||
| TIME-9.1 | момент события | стенные часы через единую точку (TIME-5) |
|
||||
| TIME-9.2 | длительность операции | монотонные часы процесса |
|
||||
|
||||
**Почему.** Стенные часы подводит NTP: они могут шагнуть назад, и тогда
|
||||
**ПОЧЕМУ.** Стенные часы подводит NTP: они могут шагнуть назад, и тогда
|
||||
интервал, посчитанный вычитанием, выйдет отрицательным, а при шаге вперёд —
|
||||
правдоподобным, но выдуманным. Монотонные часы, наоборот, не годятся для
|
||||
меток: их ноль произволен и не переживает перезапуск процесса, так что вне
|
||||
@@ -148,7 +148,7 @@ prefix: TIME
|
||||
**ДОЛЖЕН.** Преобразование в зону пользователя происходит при выводе и не
|
||||
проникает в хранение, сортировку и логи.
|
||||
|
||||
**Почему.** Как только конвертация уходит вглубь, результат вычислений
|
||||
**ПОЧЕМУ.** Как только конвертация уходит вглубь, результат вычислений
|
||||
начинает зависеть от настроек конкретного зрителя: одна и та же выборка даёт
|
||||
разные группировки, а порядок записей перестаёт быть общим для всех. Ещё
|
||||
хуже, что при конвертации в нескольких слоях её легко выполнить дважды —
|
||||
@@ -160,7 +160,7 @@ prefix: TIME
|
||||
**ДОЛЖЕН.** Значение приходит из конфигурации, значение по умолчанию —
|
||||
`UTC`.
|
||||
|
||||
**Почему.** Зашитая в код зона превращает переезд или второго пользователя в
|
||||
**ПОЧЕМУ.** Зашитая в код зона превращает переезд или второго пользователя в
|
||||
другом поясе в правку кода и релиз. Значение по умолчанию `UTC` выбрано
|
||||
потому, что оно не притворяется настроенным: показанное время совпадает с
|
||||
тем, что лежит в базе и в логах, поэтому несовпадение с ожиданиями читается
|
||||
@@ -171,7 +171,7 @@ prefix: TIME
|
||||
**ДОЛЖЕН.** «Сегодня», «за месяц» и прочие календарные границы считаются с
|
||||
явно переданной зоной, а не с системной зоной процесса.
|
||||
|
||||
**Почему.** Системная зона разная на ноутбуке разработчика и в контейнере на
|
||||
**ПОЧЕМУ.** Системная зона разная на ноутбуке разработчика и в контейнере на
|
||||
сервере, поэтому граница суток уезжает, а вместе с ней — содержимое отчёта:
|
||||
расхождение не воспроизводится там, где его заметили, и объясняется средой,
|
||||
а не кодом. Явно переданная зона делает результат функцией от аргументов.
|
||||
|
||||
Reference in New Issue
Block a user