fabrilis/docs/CODE_RULES.md
loki5512344 190ef9cc4b Add design persistence, world rendering, metrics overlay and logs
M3: STL/OBJ import with mesh validation, mass/COM/inertia, material database, RON scene with content-addressed blobs and v0->v1 migration. M4: deterministic heightmap terrain, trimesh colliders, wgpu renderer with instancing and depth, winit app with 1 kHz physics, fly camera, on-screen metrics overlay and per-frame CSV/dev logs. Docs: UI, logging, network and headless CLI plans.
2026-11-16 23:40:39 +01:00

13 KiB
Raw Permalink Blame History

Правила кода

Правила проверяются автоматически, а не на честном слове. Главный инструмент — crate tools/limits (fabrilis-limits). У каждого crate'а есть build.rs, который вызывает его, поэтому нарушение жёсткого правила ломает любую сборку (cargo build, check, clippy, test). Весь репозиторий проверяется командой cargo run -p fabrilis-limits; она же стоит в pre-commit (.githooks/).

Правила касаются только нашего кода. docs/, *.md и ref/ (локальные клоны чужих проектов, см. REFERENCES.md) не проверяются.

Проверяет fabrilis-limits (ошибка сборки)

Правило Подробности
Размер файла больше 350 строк — предупреждение, больше 500 — ошибка; на тестовые файлы не распространяется
Файлов в директории не больше 4 файлов кода (.rs, .wgsl, .rhai, .sh) в одной директории, и так в каждой директории отдельно, на любой глубине; подпапки в счёт не идут, тестовые файлы не считаются
Комментарии на английском кириллица в //, ///, //!, /* */ запрещена; строки и литералы не проверяются
Без маркеров работы TODO, FIXME, HACK, XXX в комментариях запрещены; открытая работа живёт в TODO.md
Тесты отдельно от кода см. ниже
Без файлов-свалок имена utils, util, helpers, helper, common, misc, stuff, shared для файлов и папок запрещены: файл называется по тому, что в нём лежит
Слои crate'ов зависимости идут только вниз; симуляция не зависит от render, ui, app; новый crate нужно внести в таблицу tools/limits/src/rules/layers.rs, иначе сборка падает

Тесты отдельно от кода

В файле с кодом нет ни одного теста: ни #[test], ни #[cfg(test)] mod x { ... }, ни #[cfg(test)]-хелперов. Допустимо только:

  • модульные тесты: в коде одна строка #[cfg(test)] mod tests;, а сами тесты лежат в tests.rs той же директории (foo/mod.rs → foo/tests.rs, foo/bar.rs → тоже foo/tests.rs);
  • интеграционные тесты и бенчи: папки tests/ и benches/ в crate'е;
  • общие помощники для тестов лежат в tests/<имя>/mod.rs (не common).

Тестовые файлы (tests.rs, всё в tests/ и benches/) не считаются в лимит четырёх файлов на директорию и не ограничены по размеру: один tests.rs может быть длинным. Разносить тесты по подпапкам ради лимитов не нужно — весь модуль тестируется одним файлом рядом.

Проверяют rustfmt и clippy (pre-commit с -D warnings)

Правило Чем задано
Отступы только табами rustfmt.toml: hard_tabs = true
unsafe запрещён Cargo.toml: unsafe_code = "deny"
Детерминизм: нет sin/cos/exp/pow из std, HashMap/HashSet, Instant::now, SystemTime::now clippy.toml: disallowed-methods, disallowed-types; platform и app могут разрешить время точечно
Нет unwrap, expect, panic!, todo!, unimplemented!, dbg! в обычном коде Cargo.toml: lints; в тестах разрешено (clippy.toml)
Индексация только с доказанной границей см. «Паники и индексация»
Функция не длиннее 60 строк, не больше 5 аргументов, сложность ≤ 15 clippy.toml: пороги
Каждое #[allow] объясняется: #[allow(lint, reason = "...")] allow_attributes_without_reason

Исключения оформляются точечно, с причиной, и не на весь crate без необходимости.

Паники и индексация

unwrap, expect, panic!, todo!, unimplemented! и dbg! в библиотечном коде запрещены, в тестах разрешены. Индексация (v[i]) паникует сама, и линтер её не ловит, поэтому: индексировать можно только там, где граница доказана структурой — фиксированный массив, срез, полученный в этой же функции с проверкой, индекс из конструктора. Иначе — итераторы, get, chunks. Паника допустима лишь как утверждение «сюда нельзя попасть» в месте, куда данные из файла или из сети не доходят; в тестах это проверяется отдельным тестом.

Лимиты и как их держать

Списка исключений для файлов кода нет: если файл упирается в лимит, он делится на подмодули по смыслу. Декодер RISC-V, MNA-матрица и FEM собираются из маленьких модулей (по шагам ISA, по типам элементов, по решателям), а не из одного «большого» файла. Если подпапки не помогают, это повод пересмотреть структуру, а не завести исключение.

Лимит четырёх файлов действует на каждую директорию независимо: в src/ может лежать 4 файла и 6 подпапок, и в каждой подпапке снова 4 файла и свои подпапки, без ограничения глубины. Тесты в этот счёт не входят, поэтому mod.rs, три модуля и tests.rs — это нормальная директория, а не пять файлов.

Dev-зависимости

proptest и criterion разрешены как dev-зависимости (D26): в продуктовую сборку они не входят. Свои тесты на seeded core::rng остаются основой, потому что тот же генератор нужен Monte Carlo.

Принципы

  • KISS: самое простое решение, которое работает; без заглушек «на будущее».
  • DRY: одно знание — одно место (device tree из карты памяти, единицы в core).
  • SOLID: один модуль — одна причина меняться; зависимости через трейты (PhysicsBackend, Cpu, Device); зависимости только вниз по слоям.

Правила проекта (проверяются ревью)

  • В движке нет кода под конкретную конструкцию: всё через данные, детали-плагины и сценарии; конструкции лежат в examples/.
  • Crate'ы симуляции не зависят от GPU, окна и Bevy.
  • Единицы СИ через newtype из core::units, без голых f64 в публичных API физики.
  • Новая внешняя зависимость обосновывается записью в DECISIONS.md (мы пишем своё, где это разумно).
  • Архитектурное изменение сопровождается записью в DECISIONS.md.

Логирование (обязательно с первого дня)

Код пишет диагностику сразу, а не «потом добавим». Единая точка — фасад fabrilis_core::log с уровнями; приложение ставит приёмник (stderr, файл, dev-лог). println!/eprintln! в библиотечном коде запрещены: только main для --help и ошибок запуска.

Уровень Когда Пример
error работать дальше нельзя не создался GPU-девайс, не загрузился проект
warn работаем, но деградация шейдер не поддержан, шаг не сошёлся, поле не распознано
info жизненный цикл, один раз на событие старт, seed и размер мира, загружено N деталей, режим
debug сводки и важные изменения раз в секунду FPS/TPS/RTF, смена камеры, решение сходимости
trace покадрово/пошагово, только для разбора входные события, каждый шаг решателя, пики контактов

Правила:

  • Уровень выбирается по смыслу события, а не по желанию. Горячий цикл логирует только trace и только после проверки уровня: строка не должна строиться, если уровень выключен.
  • Логи не влияют на симуляцию: логгер не меняет порядок, состояние и время. В crate'ах симуляции по-прежнему нет Instant::now/SystemTime::now; время для логов ставит приёмник в app.
  • Пишем факты в виде key=value, а не склейку предложений: frame=120 frame_ms=18.4 physics_max_ms=0.6 trigger=contact.
  • Ошибки и деградации логируются там, где возникли, а не только наверху.
  • Не логировать секреты и личные пути; большие буферы и меши не дампить.
  • Сообщения на английском (как комментарии), уровни и поля — стабильные.
  • Тесты: формат строки, парсеры, поведение выключенного уровня (строка не форматируется), неизменность golden-хеша при включённых логах.

log/tracing сейчас не берём: нужен свой минимальный фасад без зависимостей и с контролем детерминизма (D35). Если понадобится экосистема, заменим фасад, не меняя места вызовов.

Идеи на потом (пока не включены)

Каждый пункт можно включить отдельным шагом, когда проект дорастёт.

Идея Зачем
cargo-deny (лицензии, уязвимости, дубли версий, запрещённые crate'ы) гигиена зависимостей
cargo-machete неиспользуемые зависимости
missing_docs, missing_errors_doc, missing_panics_doc для нижних слоёв документированный публичный API
Касты cast_possible_truncation, cast_precision_loss в crate'ах симуляции потеря точности между u64 нс и f64
float_cmp: сравнение f64 через допуск, а не == корректная численная логика
Фаззинг (cargo-fuzz) для импорта мешей, форматов RON, декодера RISC-V парсеры устойчивы к мусору
Мутационное тестирование (cargo-mutants) и покрытие (cargo-llvm-cov) для core, analog, cpu тесты реально ловят ошибки
Порог регрессии бенчмарков в автоматическом прогоне (своя утилита замеров) скорость не падает незаметно
Conventional Commits и commit-msg хук читаемая история
Проверка, что каждый crate описан в ARCHITECTURE.md документация не отстаёт
Лимит на число unsafe-блоков и место (только cpu, с обоснованием) контроль рисков