# Стандарты код-ревью (LLM Test Bench) Дата ввода: 2026-09-24. Пересмотр: **2026-09-26** (процесс приведён к реальности репозитория, добавлены автоматические проверки — см. §9). Язык проекта — русский (код, комментарии, ТЗ, ревью). Этот документ — стандарт ревью для этого проекта. Он отвечает на три вопроса: *что* считается хорошим кодом, *как* его проверять и *кто* за что отвечает. Короткая версия для одного прохода — в файле `ЧЕК-ЛИСТ-ревью.md`. Записи о проведённых ревью — в `ЖУРНАЛ-ревью.md`. --- ## 1. Зачем это нужно Раньше в проекте не было единых требований: где-то глухие `except Exception`, где-то `%`-форматирование, где-то f-строки, нигде не было автоматической проверки. Качество «плавало» от файла к файлу и от автора к автору. Цель стандарта не в том, чтобы сделать код красивым, а в том, чтобы **новый код не ухудшал то, что уже есть**, и чтобы любой мог проверить правку за 10 минут без споров о вкусовщине. **Главный принцип (изменение 2026-09-26).** Стандарт проверяет **новые и изменённые строки**, а не весь проект. В проекте 20 000 строк и сотни старых `%`-форматирований; требование «сначала перепиши всё» невыполнимо, а значит вредно — такое правило обходят. Поэтому долг легаси **заморожен** (§9.3), а требования предъявляются к тому, что мы пишем сейчас. --- ## 2. Уровень качества: обязательное и рекомендуемое Правила делятся на два слоя. Это снимает споры «а можно ли так»: ### Обязательное (блокирующее) Не проходит ревью и не собирается pre-commit. Если не выполняется — правим до слияния или фиксируем исключение в журнале ревью. | № | Правило | Как проверяется | Почему | |---|---------|-----------------|--------| | O1 | Код компилируется; нет мёртвых импортов | авто: `ruff check` (E/F) + `check_imports.py` | Мёртвый импорт или синтаксическая ошибка — 30% багов в начале работы | | O2 | Нет глухого `except`, который прячет баг | авто: `check_review.py` R1 | Глухой except убивает диагностику и портит статистику прогонов | | O3 | Переменная исключения читается | авто: `check_review.py` R2 | `except Exception as e:` с неиспользуемым `e` — мусор: имя обещает разбор | | O4 | Нет магических чисел без имени | авто (подсказка): `check_review.py` R3 | `DEFAULT_REASONING_ALLOWANCE = 2048` — образец; `10000` в коде — нет | | O5 | Файл проходит `ruff check` по блокирующим правилам (E/F/B) | авто: pre-commit | Автоматизированная часть O1–O4 | | O6 | Покрытие изменения тестами | частично авто: `check_review.py` R4 + глазами | Новая логика без проверки — риск для следующего этапа | ### Рекомендуемое (стилевое) Хорошо бы выполнять, но не блокирует слияние и не роняет pre-commit. | № | Правило | Как проверяется | Пояснение | |---|---------|-----------------|-----------| | P1 | f-строки вместо `%` | авто (подсказка): `check_review.py` R5 | Новый код — на f-строках. Старые `%` переписываем по желанию при правке строки | | P2 | Короткие функции и методы | руками | Метод >15 строк — подумайте, не разложить ли | | P3 | Имена говорят о назначении | руками | `t0` ок в локальном таймере, но `response_payload` лучше `data` | Почему P1–P3 не обязательные: в проекте ~20 300 строк и 686 старых `%`-форматирований. Переписывать всё сразу — бесполезно, ревьюер утонет. Новые файлы и новые строки пишем на f-строках; старое не трогаем без причины. --- ## 3. Что проверяем в первую очередь (приоритеты) Проект специфичный — локальные модели, GPU, HTTP-сервер, GUI. Поэтому порядок проверки: 1. **Обработка ошибок и сбоев.** Это сердце проекта. Сбой сервера или сети не должен ронять прогон или портить статистику. Смотрите: не глухой ли except, читаются ли переменные, не прячется ли реальная ошибка под «сбой стенда». 2. **Файлы, работающие с файлами и процессами.** `gguf_scanner.py`, `server_manager.py`, `server_cmd.py`, `importer.py`, `runner.py`, `report.py`. Ошибки тут стоят дороже всего. 3. **Связка интерфейса с сервером.** `ui/*`, `main_window.py`, `models_panel.py`, `server_panel.py`. GUI-код не должен падать молча. 4. **Логика проверок ответов.** `checks.py`, `local_agent.py`, `judge.py`, `generators.py`. От них зависит достоверность всех отчётов. 5. **Данные и конфиг.** `config.py`, `database.py`, `testsets.py`. Если правка в файлах первых трёх пунктов — проверяем внимательно, по всем пунктам чек-листа. Если в «мелких» — можно покороче. **Отдельно — правила проекта, которые нельзя вывести из общего кода.** Они записаны в документации проекта и стоят дороже любого стиля: - пустой ответ — провал при любой проверке; пропуск (`passed=None`) — не провал и не идёт в знаменатель; - «метрика считается» ≠ «метрика показывается» — проверять оба конца; - новые поля в `RunResult` — только в конец (стережёт `check_history_tree.py`); - состояние берём у переключателя, а не у `isVisible()`; - `setRowCount()` не удаляет виджеты ячеек; - свой `setStyleSheet` у виджета бьёт стиль приложения. --- ## 4. Процесс ревью ### 4.0. Как это устроено здесь У проекта **нет удалённого репозитория** — `git remote` пуст, и «открыть Pull Request» технически невозможно. Поэтому ревью идёт **локально, на ветке**, а вердикт пишется в `ЖУРНАЛ-ревью.md`. Это не упрощение ради удобства: без записи вердикт нигде не остаётся, и через месяц никто не скажет, почему код такой. Если удалённый репозиторий появится, меняется только способ доставки: вердикт и комментарии переезжают в PR, а §4.2–4.4 остаются как есть. ### 4.1. Ветка ``` git checkout -b review/<тема> # например review/speed-metrics ``` В `master` не коммитим напрямую. Правка должна быть видна как отдельный набор изменений — иначе её нечего ревьюить. ### 4.2. Самопроверка автора (до передачи на ревью) ``` .venv/Scripts/python.exe -m ruff check . .venv/Scripts/python.exe -m ruff format --check . .venv/Scripts/python.exe check_imports.py .venv/Scripts/python.exe check_review.py --staged .venv/Scripts/python.exe -m pre_commit run --all-files ``` Все должны пройти без блокирующих. Если `check_review.py` показывает только «советы» — это не блокер, но прочитайте их: правило R3 (магическое число) часто указывает на настоящее решение, которое забыли назвать. `check_*.py`, связанные с правкой, — прогнать. Полный прогон и сводку по всем проверкам даёт `check_all.py`. ### 4.3. Ревью (ревьюер) 1. `pre-commit run --all-files` должен пройти. 2. Проходим по чек-листу `ЧЕК-ЛИСТ-ревью.md` — 12 пунктов, 10 минут. Пункты, помеченные «авто», уже проверены машиной: смотрим на них только если инструмент молчит, а глаз видит проблему. 3. Оцениваем по шкале §4.4. 4. Комментарии — конкретные: что не так и как лучше. Не «тут криво», а «`except Exception` без чтения — убьёт диагностику; либо уберите, либо пишите в лог». ### 4.4. Шкала оценки | Оценка | Значение | |--------|----------| | approve | всё ок, можно сливать | | request changes | есть блокирующие замечания (O1–O6), нужно доработать | | comment | неблокирующе, на ваше усмотрение (P1–P3) | `request changes` от любого ревьюера — правка не сливается. `approve` при открытом `request changes` не засчитывается. ### 4.5. Запись вердикта Каждое ревью оставляет строку в `ЖУРНАЛ-ревью.md`: ``` ## 2026-09-26 · review/speed-metrics · approve Ревьюер: CodeReviewExpert Ревизия: a1b2c3d Проверено: ruff check, format --check, check_review --staged, check_speed_metrics (68) Находки: нет Примечания: <необязательно> ``` Правила журнала: - **append-only.** Записи не правятся и не удаляются — журнал это история, а не доска. Передумали — пишем новую запись со ссылкой на старую. - вердикт `request changes` пишем тоже. «Отклонили» — это факт, который нужен. - если обошли hook (`--no-verify`) или приняли исключение из O-правила — это пишется здесь, с причиной. Исключение без записи считается нарушением. ### 4.6. Слияние ``` git checkout master git merge --no-ff review/<тема> ``` `--no-ff` — чтобы в истории осталась видна граница правки: по ней потом ищут, «какой коммит что принёс». --- ## 5. Блокирующие замечания — конкретика Если ревьюер видит одно из этого — `request changes`: - **`except` без следа** — `as e:` без `e`, пустое тело, нет лога. См. O2, O3. - **Магическое число** без имени и комментария в «горячем» коде (сравнение, лимиты, таймауты). - **Новый модуль без покрытия** тестами (`check_*.py`) — см. O6. - **`ruff check`** падает по блокирующим правилам (E, F, B). - **Синтаксис/импорты** — файл не парсится, мёртвый импорт. - **Отладка в коде** — `breakpoint()`, `pdb.set_trace()` (R7). - **Изменено поведение без предупреждения** — например, поменяли знаменатель счёта в `runner.py` и не сказали, что выпал старый кейс. --- ## 6. Автоматизация (что уже настроено) Проверено 2026-09-26: `ruff 0.16.8`, `pre-commit 4.6.2`, hook установлен в `.git/hooks/pre-commit`. - **`ruff.toml`** — линтер и форматтер. Блокирующие правила: `E`, `F`, `B`. `TRY300` намеренно выключен (был одновременно в `select` и в `ignore` — в конфиге было написано одно, а работало другое), `UP*` и `SIM*` — в `ignore` с пояснениями прямо в конфиге. - **`check_review.py`** — то, что ruff не проверяет: правила R1–R7 из чек-листа. Режимы: `--staged` (pre-commit), `--diff REV`, `--all` (аудит легаси), `--file PATH`. Отказ от правила — комментарий `# noqa` на строке. - **`.pre-commit-config.yaml`** — четыре hook-а: `ruff check`, `ruff format --check`, `check_imports.py`, `check_review.py --staged`. Формат стоит именно как `--check`: авто-правка в hook-е молча переписывает файлы, и в diff попадает не то, что человек написал. - **`check_*.py`** — предметные проверки проекта (см. README.md, раздел «Проверки»). Это и есть покрытие из правила O6. - **CI** (`.github/workflows/ci.yml`) — то же самое, но на каждый push и pull request: `ruff check`, `ruff format --check`, `check_imports.py`, аудит `check_review.py --all --no-fail`, а на Windows — `check_testsets`, `check_generators`, `check_infra`. Проверки, которым нужен живой `llama-server`, в CI не гоняются: сервера на раннере нет. ### Установка (один раз на машину) ``` .venv/Scripts/python.exe -m pip install --quiet pre-commit ruff .venv/Scripts/python.exe -m pre_commit install ``` --- ## 7. Что не меняем (границы стандарта) - **Не требуем переписывать весь старый код** под f-строки и 3.13-синтаксис. Это отдельная большая задача, не часть ревью. - **Не вводим новых инструментов** без согласования. Ruff выбран потому, что он один заменяет линтер+форматтер и уже в venv. - **Не ловим вкусовщину** (формат, отступы) вручную — это делает `ruff format`. - **Не блокируем по легаси.** Замечание к старой строке, которую правка не трогала, — не повод для `request changes`. Иначе правку нельзя сделать никогда. --- ## 8. Роль ревьюера (CodeReviewExpert) Ревьюер не правит код — он оценивает по стандарту. Главная ценность — указать на риск в обработке ошибок и связке с сервером (п. 3), а не на отступы. Конкретика важнее количества комментариев: один точный комментарий о глухом `except` дороже десяти «хорошо». Инструмент — не ревьюер. `check_review.py` закрывает механическую часть (§9.1) и молчит о смысле: он не отличит верный знаменатель от неверного. Проход по чек-листу он не отменяет, а сокращает. --- ## 9. Состояние механизма на 2026-09-26 Раздел намеренно с числами: стандарт без измеренного состояния — это пожелание, а не стандарт. ### 9.1. Что автоматизировано, а что нет | Пункт чек-листа | Автомат | |-----------------|---------| | O1 компиляция, мёртвые импорты | `ruff check` E/F + `check_imports.py` | | O2 глухой except | `check_review.py` R1 (блок) | | O3 нечитаемая переменная исключения | `check_review.py` R2 (блок) | | O4 магические числа | `check_review.py` R3 (совет) — решает человек | | O5 блокирующие правила ruff | pre-commit | | O6 покрытие | `check_review.py` R4 (совет, только новый модуль) — решает человек | | P1 f-строки | `check_review.py` R5 (совет) | | P2–P3 длина и имена | **руками** | | Сбой сервера не портит статистику, пустой ответ ≠ провал | **руками** (смысл) | | GUI не падает молча, длинная операция в потоке | **руками** | | Тема не сломана | **руками** + `make_screenshots.py` | | Удаление результатов в корзину | **руками** | Честно: O4, O6 и половина смысловых пунктов остаются за человеком. Автомат здесь — подсказка, а не приговор: правило R3 срабатывает на любое число ≥ 100, и решать, магическое оно или нет, всё равно ревьюеру. ### 9.2. Что было не так до правки (найдено при ревизии) - **Стандарт был невыполним.** §4.1 требовал `ruff format --check` перед слиянием, а проверка падала на **49 файлах из 67** — правило не работало ни разу. Это и есть механизм «плавающего» качества: требование, которое все обходят. - **Процесса не существовало.** §4.2 требовал открыть Pull Request, а у репозитория нет удалённого (`git remote` пуст). Инструкция была неисполнима. - **Hook не был установлен.** `.git/hooks/` был пуст: `pre-commit install` никто не делал. - **В конфиге было противоречие.** `TRY300` стоял одновременно в `select` и в `ignore` — то есть в `ruff.toml` было написано одно, а работало другое. - **Устаревший комментарий.** `.pre-commit-config.yaml` утверждал, что «в этом проекте репозитория пока нет» — репозиторий есть с 2026-09-24. - **Число в документе не сходилось с фактом.** Стандарт говорил про «7 нарушений ruff»; фактически их было **3** — все `E402` в черновике `devtools/_icon_preview_tmp.py`, который не должен был проверяться вовсе. ### 9.3. Замороженный долг легаси (аудит `--all`, 2026-09-26) | Правило | Находок | Что это | |---------|---------|---------| | R5 `%`-форматирование | 684 | известный долг, переписываем постепенно | | R3 магические числа | 128 | кандидаты, решает человек | | R1 глухой except | **0** | закрыты правкой `474f114`, см. ниже | | R7 отладка | 0 | `print()` в модулях заменены на лог | | R6 TODO без задачи | 0 | маркеров без ссылки в коде нет | Итого после правки: **0 блокирующих, 812 советов** (684 + 128). Три блокирующие находки R1 **закрыты** правкой `review/production-readiness` (коммит `474f114`, вердикт — в журнале ревью): - `importer.export_json` и `importer.export_csv` — причина отказа пишется в лог, вызывающий по-прежнему получает `False`; - `runner.py` — неразобранный лог памяти логируется, а не превращается в молчаливый `None`; - два `print()` в `importer.py` и `runner.py` заменены на `log.warning`. Аудит `--all` теперь показывает **0 блокирующих**. Остаётся легаси без блокировки: 684 совета R5 и 128 кандидатов R3. ### 9.4. Базовая линия формата `ruff format` применён ко всему проекту **отдельным коммитом** 2026-09-26: 49 файлов из 67. После этого `ruff format --check .` проходит, и правило «формат перед слиянием» стало выполнимым. Коммит содержит **только** переформатирование — ни одной смысловой правки, поэтому его можно откатить (`git revert`) без последствий.