Наставничество в код-ревью: как учить без унижения

Одно неудачное ревью может отбить у новичка желание открывать pull request, а команда потеряет часы на споры о формулировках. Наставническое ревью устроено иначе: оно защищает код от дефектов, но одновременно объясняет автору решение, цену ошибки и следующий шаг. Ниже — рабочая схема для асинхронных ревью в GitHub, GitLab и похожих системах; она не зависит от конкретной версии платформы, но локальные правила команды нужно сверить с актуальной документацией.

Сначала договоритесь, что именно проверяет ревью

Самая частая причина унизительного ревью — у автора и проверяющего разные ожидания. Один думает, что проверяют корректность бизнес-логики, другой оставляет двадцать замечаний к отступам и именам переменных. Автор получает ощущение, что его работу разобрали по мелочам, хотя критерии не были объявлены.

Перед началом полезно зафиксировать в описании изменения четыре пункта:

• какую задачу решает изменение и что сознательно осталось за пределами pull request;
• какие части нужно проверить в первую очередь: миграцию, права доступа, обработку ошибок или производительность;
• какие компромиссы уже приняты и почему;
• какой результат нужен от ревьюера: найти дефекты, проверить архитектурное решение или помочь автору освоить участок системы.

Это не бюрократия. Короткий контекст уменьшает число догадок и не заставляет новичка защищаться от вопросов, которых он не ожидал.

Три режима ревью и их цена

Ревью не всегда должно выглядеть одинаково. Ошибка в расчёте платежа требует жёсткой остановки, а спор о названии локальной переменной — нет. Полезно заранее выбрать режим, иначе проверяющий начнёт учить всему сразу.

Режим можно указать прямо в описании изменения: «Нужна проверка безопасности» или «Хочу понять, где в этом модуле принято размещать валидацию». Такой сигнал задаёт глубину ревью и снижает риск, что наставник превратит небольшую задачу в полный аудит проекта.

Хорошее замечание не доказывает, что автор ошибся. Оно помогает ему самостоятельно увидеть риск и сделать следующий патч сильнее.

Как формулировать замечания, после которых можно действовать

У наставнического комментария есть четыре части: наблюдение, риск, рекомендация и способ проверки. Не обязательно писать их отдельными предложениями, но смысл должен быть понятен.

1. Назовите место. «В обработчике отмены заказа» лучше, чем «в этом коде».
2. Опишите поведение. Укажите, что происходит при пустом ответе, повторном запросе или отсутствии прав.
3. Объясните цену. Например: повторный вызов создаёт две записи, а ошибка проявится только при сетевом тайм-ауте.
4. Предложите действие. Спросите, можно ли сделать проверку идемпотентности, добавить тест на повторный запрос или вынести правило в существующий сервис.
5. Дайте критерий готовности. После исправления должен появиться тест на повторную отмену, а сценарий с тайм-аутом не должен менять состояние дважды.

Сравните две формулировки:

• «Ты опять не учёл ошибки API. Переделай нормально».
• «Здесь код считает любой ответ успешным. При статусе ошибки заказ останется в промежуточном состоянии. Добавьте обработку неуспешного ответа и тест на тайм-аут; после этого я повторно проверю этот сценарий».

Во втором варианте нет мягкости ради мягкости. В нём просто есть проверяемое утверждение и понятный маршрут исправления.

Отделяйте блокер от предпочтения

Комментарий должен показывать срочность. Удобно использовать три уровня:

• Блокер. Изменение нельзя принимать: есть риск потери данных, обхода авторизации, падения критического сценария или нарушения согласованного контракта.
• Важное замечание. Проблему стоит исправить в этом изменении, но она не делает выпуск немедленно опасным.
• Предложение. Улучшение читаемости или будущего сопровождения. Автор может принять его сейчас или вынести в отдельную задачу.

Не называйте блокером личное предпочтение. Если команда не зафиксировала правило, спор о порядке аргументов, длине функции или названии переменной не должен останавливать выпуск. Такие замечания лучше формулировать как вопрос или предложение и объяснять, какую проблему они решают.

Ревью — это диалог, а не список приговоров

Наставник не обязан писать длинную лекцию под каждой строкой. Но он должен оставить автору возможность ответить: «Я выбрал это намеренно, потому что…». Вопрос «Как вы проверяли повторный запрос?» открывает обсуждение. Фраза «Вы не понимаете, как работает очередь» его закрывает.

Если решение спорное, сначала спросите о намерении, затем объясните риск. Это особенно важно для новичка: один и тот же фрагмент может быть ошибкой, временным компромиссом или частью невидимого контракта с другой системой.

Автору тоже нужна роль в процессе. Он отвечает на замечания по существу, отмечает исправленные места и пишет, если предлагает оставить решение как есть. Наставник проверяет именно изменившийся участок, закрывает решённые обсуждения и не поднимает заново вопрос без новой причины.

Когда продолжать в комментариях, а когда созваниваться

Асинхронное обсуждение подходит для локальной ошибки, ссылки на документацию и небольшого изменения. Созвон или совместный просмотр экономят время, когда за десять минут появляется несколько одинаковых комментариев, спор затрагивает архитектуру или автор уже не понимает, какое решение от него ждут.

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

Что ломает наставнический подход

Проблема обычно не в одной грубой фразе, а в повторяющемся процессе.

• Публичный разбор личности. Обсуждают автора, а не строку кода: «Ты невнимательный», «от тебя всегда одно и то же». Такие реплики не дают действия для исправления.
• Поток мелочей без приоритетов. Десятки замечаний к стилю прячут один дефект в обработке ошибок. Сначала отмечайте риски, затем второстепенные улучшения.
• Разные стандарты для разных людей. Новичка заставляют исправлять каждую мелочь, а опытному разработчику прощают те же нарушения. Это быстро разрушает доверие к процессу.
• Ревью без времени на объяснение. Если задача горит, наставничество превращается в набор коротких приказов. Лучше честно выбрать контрольный режим и назначить отдельный разбор после выпуска.
• Нет повторной проверки. Автор исправляет замечание, но никто не смотрит результат. Так ревью становится формальностью, а полезная обратная связь не замыкается.

Как понять, что ревью действительно учит

Не измеряйте успех количеством комментариев. Большое число замечаний может означать плохую подготовку pull request, неясные правила или желание ревьюера показать экспертность.

Смотрите на другие сигналы:

• автор заранее добавляет тесты для сценариев, о которых раньше спрашивал наставник;
• повторяющиеся вопросы превращаются в документацию, шаблон pull request или автоматическую проверку;
• блокирующие замечания становятся точнее, а обсуждения — короче;
• автор может объяснить, почему выбрал решение, даже если оно отличается от предложения ревьюера;
• после ревью команда понимает, какое правило стоит изменить в процессе, а не только в конкретном файле.

Если вы хотите измерять процесс численно, фиксируйте время от открытия ревью до принятия, число повторных циклов и долю изменений, возвращённых из-за одного и того же класса ошибки. Сравнивать разработчиков между собой по этим цифрам опасно: на результат влияют размер задачи, срочность и сложность системы.

Что делать дальше

На следующем ревью выберите один режим и напишите его в описании изменения. Для каждого блокирующего комментария добавьте риск и проверку готовности, а все предложения по вкусу отделите от обязательных исправлений. Через несколько ревью соберите три повторяющиеся ошибки и вынесите их в короткий чек-лист или автоматическую проверку. Так наставничество перестаёт зависеть от удачной формулировки конкретного человека и становится частью инженерного процесса.

Термин: блокер — замечание, которое должно быть устранено до принятия изменения, потому что риск от него выше пользы от немедленного выпуска.