ПОЧЕМУ стало ключевым словом, язык поднят до версии 2
- метка обоснования пишется заглавными и вошла в словарь набора: скелет правила теперь целиком из ключевых слов, а не смесь `**ДОЛЖЕН.**` и `**Почему.**`; в переводе на другой язык метка меняется как остальные слова (ПОЧЕМУ / WHY), 235 вхождений заменены - метки правила выделены из шкалы в отдельный перечень: ПОЧЕМУ и МЕХАНИЗИРОВАНО обязательности не задают, а размечают части, и стандартом не даются ни в одном языке — раньше МЕХАНИЗИРОВАНО висело строкой в таблице модальности - версия языка поднята до 2, потому что изменение формы меняет чтение уже написанного текста; строка о версии в двенадцати конвенциях перечисляет теперь и метки, а служебные слова сценария в неё по-прежнему не входят
This commit is contained in:
+16
-16
@@ -8,9 +8,9 @@ extends: arch/time.md
|
||||
Как требования базового слоя выполняются в Go-коде: откуда берётся «сейчас»,
|
||||
в каком виде время попадает в базу и в логи, что делать с зонами.
|
||||
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и отметка
|
||||
МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 1 — тогда и
|
||||
только тогда, когда написаны заглавными.
|
||||
Ключевые слова ДОЛЖЕН, НЕ ДОЛЖЕН, СЛЕДУЕТ, НЕ СЛЕДУЕТ, ДОПУСКАЕТСЯ и метки
|
||||
ПОЧЕМУ и МЕХАНИЗИРОВАНО толкуются как описано в языке конвенций версии 2 —
|
||||
тогда и только тогда, когда написаны заглавными.
|
||||
|
||||
## Правила
|
||||
|
||||
@@ -19,7 +19,7 @@ extends: arch/time.md
|
||||
**ДОЛЖЕН.** Текущее время приходит из `store.Now()`, возвращающего
|
||||
`time.Now().UTC()`, а не из `time.Now()` по коду.
|
||||
|
||||
**Почему.** Единая точка даёт гарантированный UTC и один формат: ни одна
|
||||
**ПОЧЕМУ.** Единая точка даёт гарантированный UTC и один формат: ни одна
|
||||
ветка кода не может о них забыть. Разъехавшиеся зоны чинятся только чтением
|
||||
всех записей — по метке `2026-06-28T11:23:45Z` уже не видно, была ли она
|
||||
когда-то локальной, и восстановить смещение задним числом не по чему.
|
||||
@@ -33,7 +33,7 @@ extends: arch/time.md
|
||||
**ДОЛЖЕН.** Пара функций поверх `time.RFC3339` — единственный способ
|
||||
получить строку времени и прочитать её обратно.
|
||||
|
||||
**Почему.** Layout, набранный по месту вызова, превращает формат хранения в
|
||||
**ПОЧЕМУ.** Layout, набранный по месту вызова, превращает формат хранения в
|
||||
свойство каждой отдельной строки кода. Фиксированная ширина (GTIM-4) и
|
||||
взаимная обратимость записи и чтения держатся ровно до первого второго
|
||||
layout — а расхождение проявится не на записи, а при сравнении значений,
|
||||
@@ -49,7 +49,7 @@ layout — а расхождение проявится не на записи,
|
||||
| GTIM-3.1 | сама точка `store.Now()` | внутри неё вызов `time.Now()` и происходит |
|
||||
| GTIM-3.2 | обёртка измерения длительности | приведение к UTC срезает монотонную составляющую (GTIM-10) |
|
||||
|
||||
**Почему.** GTIM-1 без механической проверки держится на внимании, а
|
||||
**ПОЧЕМУ.** GTIM-1 без механической проверки держится на внимании, а
|
||||
`time.Now()` пишется рефлекторно — и в новом коде, и в мелкой правке;
|
||||
нарушение молчит до тех пор, пока процесс не окажется в не-UTC зоне.
|
||||
Исключения перечисляются исчерпывающе, потому что каждое из них — само по
|
||||
@@ -63,7 +63,7 @@ layout — а расхождение проявится не на записи,
|
||||
`//nolint:forbidigo // <причина>` на строке вызова; exclude-записи в
|
||||
конфигурации линтера для него не заводятся.
|
||||
|
||||
**Почему.** Запись в конфиге — второй реестр тех же двух мест: она адресует
|
||||
**ПОЧЕМУ.** Запись в конфиге — второй реестр тех же двух мест: она адресует
|
||||
исключение путём к файлу, отвязывается при переносе кода и продолжает
|
||||
разрешать `time.Now()` там, где исключения уже нет, — молча. Директива
|
||||
переезжает вместе с кодом, и grep по `nolint:forbidigo` даёт весь список —
|
||||
@@ -77,7 +77,7 @@ layout — а расхождение проявится не на записи,
|
||||
|
||||
**ДОЛЖЕН.** Каноническое значение в колонке — `2026-06-28T11:23:45Z`.
|
||||
|
||||
**Почему.** Строки в колонке `TEXT` сравниваются побайтово, поэтому
|
||||
**ПОЧЕМУ.** Строки в колонке `TEXT` сравниваются побайтово, поэтому
|
||||
лексикографический порядок совпадает с хронологическим только при
|
||||
одинаковых ширине и форме. Значение с долями секунды сортируется **раньше**
|
||||
целой секунды того же момента (`.` меньше `Z`), то есть ломаются и
|
||||
@@ -91,7 +91,7 @@ layout — а расхождение проявится не на записи,
|
||||
|
||||
**НЕ ДОЛЖЕН.** Ни как layout вывода, ни как формат хранения.
|
||||
|
||||
**Почему.** Он отбрасывает хвостовые нули, из-за чего длина строки зависит
|
||||
**ПОЧЕМУ.** Он отбрасывает хвостовые нули, из-за чего длина строки зависит
|
||||
от значения: соседние записи получают разную ширину, и свойство, на котором
|
||||
держится GTIM-4, исчезает незаметно. Проверка «формат корректен» при этом
|
||||
проходит — отказывает только порядок.
|
||||
@@ -102,7 +102,7 @@ layout — а расхождение проявится не на записи,
|
||||
к каноническому виду явно, а не считается каноническим по факту успешного
|
||||
разбора.
|
||||
|
||||
**Почему.** `time.Parse(time.RFC3339, …)` принимает и доли секунды, и
|
||||
**ПОЧЕМУ.** `time.Parse(time.RFC3339, …)` принимает и доли секунды, и
|
||||
офсеты, отличные от `Z`, — разбор шире вывода. Канонический вид гарантирует
|
||||
**писатель**, а не читатель; пока писатель один, этого достаточно, но
|
||||
значение из чужой системы, положенное в базу как пришло, нарушает GTIM-4 и
|
||||
@@ -114,7 +114,7 @@ Go-механика, из-за которой его легко нарушить
|
||||
|
||||
**СЛЕДУЕТ.** В запрос идёт результат `FormatTime`.
|
||||
|
||||
**Почему.** Колонка — `TEXT`, и передача `time.Time` отдаёт форматирование
|
||||
**ПОЧЕМУ.** Колонка — `TEXT`, и передача `time.Time` отдаёт форматирование
|
||||
драйверу: появляется вторая точка формата вне `FormatTime` (GTIM-2), с
|
||||
собственным layout, который меняется вместе с версией драйвера, а не вместе
|
||||
с конвенцией.
|
||||
@@ -132,7 +132,7 @@ func utcTime(_ []string, a slog.Attr) slog.Attr {
|
||||
}
|
||||
```
|
||||
|
||||
**Почему.** `slog` по умолчанию UTC не даёт: встроенные хендлеры пишут
|
||||
**ПОЧЕМУ.** `slog` по умолчанию UTC не даёт: встроенные хендлеры пишут
|
||||
время в зоне самого `time.Time`, то есть в локальной зоне процесса — на
|
||||
ноутбуке разработчика логи молча уезжают в `+03:00`. Умолчание тихое,
|
||||
неверная зона выглядит как совершенно валидное время, а записи из разных
|
||||
@@ -143,7 +143,7 @@ func utcTime(_ []string, a slog.Attr) slog.Attr {
|
||||
**ДОПУСКАЕТСЯ.** `JSONHandler` пишет миллисекунды — три знака, и это не
|
||||
приводится к секундной точности GTIM-4.
|
||||
|
||||
**Почему.** Явное разрешение нужно, чтобы GTIM-4 не читался как требование
|
||||
**ПОЧЕМУ.** Явное разрешение нужно, чтобы GTIM-4 не читался как требование
|
||||
одной точности везде. Ширина фиксируется на носитель: три знака в логе —
|
||||
такая же фиксированная ширина, и свойство, ради которого GTIM-4 существует, не
|
||||
нарушено. Общее у лога и базы одно — зона (GTIM-8).
|
||||
@@ -153,7 +153,7 @@ func utcTime(_ []string, a slog.Attr) slog.Attr {
|
||||
**ДОПУСКАЕТСЯ.** Обёртка вызывает `time.Now()` и считает `time.Since` — с
|
||||
локальным `//nolint`.
|
||||
|
||||
**Почему.** `store.Now()` приводит время к UTC через `.UTC()`, а это
|
||||
**ПОЧЕМУ.** `store.Now()` приводит время к UTC через `.UTC()`, а это
|
||||
срезает монотонную составляющую `time.Time`. Интервал, посчитанный по таким
|
||||
меткам, зависит от подводки часов: перевод назад даёт отрицательную
|
||||
длительность, скачок вперёд — выброс в измерениях, и оба случая
|
||||
@@ -164,7 +164,7 @@ func utcTime(_ []string, a slog.Attr) slog.Attr {
|
||||
|
||||
**ДОЛЖЕН.** База зон вшивается в бинарь.
|
||||
|
||||
**Почему.** Без неё `LoadLocation` зависит от файлов зон в системе, которых
|
||||
**ПОЧЕМУ.** Без неё `LoadLocation` зависит от файлов зон в системе, которых
|
||||
в минимальном образе нет: отказ происходит в рантайме, на первой же попытке
|
||||
применить зону, — то есть после выкладки, а не на сборке. Импорт именно в
|
||||
`main` держит это решение в одном видимом месте, а не в случайном пакете,
|
||||
@@ -175,7 +175,7 @@ func utcTime(_ []string, a slog.Attr) slog.Attr {
|
||||
**ДОЛЖЕН.** Зона из конфига используется в шаблонах и форматтерах
|
||||
представления, но не в хранимых значениях и не в вычислениях.
|
||||
|
||||
**Почему.** Зона отображения — настройка, и её меняют. Протекая в
|
||||
**ПОЧЕМУ.** Зона отображения — настройка, и её меняют. Протекая в
|
||||
вычисления и хранение, она делает уже записанные данные зависимыми от
|
||||
текущего значения настройки: смена зоны задним числом сдвигает границы
|
||||
суток у того, что давно посчитано и сохранено.
|
||||
|
||||
Reference in New Issue
Block a user