Протокол код-ревью по записи: как превратить обсуждение в проверяемые замечания
Как оформить устное код-ревью: привязать замечание к версии и месту кода, отделить вопрос от ошибки, сохранить причину и способ проверки исправления.
Зафиксируйте границы обсуждения
Устное код-ревью часто оставляет фразы «здесь надо иначе» и «это уже проверяли». Через день непонятно, к какой версии они относились и что именно нужно сделать. Задача протокола — сохранить технический смысл разговора так, чтобы автор изменения и проверяющий могли вернуться к одному месту кода.
До записи договоритесь с участниками о её использовании и месте хранения. Не отправляйте секреты, токены и закрытый код в сервисы, которые не разрешены правилами проекта. Если онлайн-обработка допустима, Транскрибатор поможет получить текст аудио. Доступность текста не заменяет разрешение на его распространение.
Запишите название изменения, обсуждавшуюся версию или commit hash, дату и ссылку на место работы команды. Отдельно отметьте, показывали ли код на экране и меняли ли его во время разговора. Если несколько ревизий смешались, не присваивайте всем репликам одну версию: восстановите последовательность либо пометьте спорный участок для уточнения.
Извлеките замечания, а не все реплики
Сначала прочитайте расшифровку целиком, затем выделите законченные технические мысли. Одно обсуждение может содержать вопрос, гипотезу, подтверждённую проблему, предложение и согласованное решение. Они не должны превращаться в одинаковые «обязательные исправления». Благодарность или объяснение автора тоже не является задачей.
Для каждого кандидата сохраните время в записи и короткую цитату либо явно обозначенный пересказ. Проверьте отрицания: «не воспроизводится» и «воспроизводится» ведут к разным действиям. Сверьте названия функций, числа и условия по правилам проверки расшифровки. Распознавание речи может ошибиться в английском идентификаторе; это не свидетельство ошибки в программе.
Используйте понятные метки: «вопрос», «нужна проверка», «исправление согласовано», «необязательное улучшение». Команда сама определяет обязательность и условия принятия изменения. Слово «блокирует» ставьте только при явно согласованном требовании. Не повышайте серьёзность замечания потому, что говорящий произнёс его уверенно.
Привяжите мысль к проверенному месту кода
Откройте обсуждавшуюся ревизию в привычном инструменте команды. Найдите файл, функцию или другой устойчивый контекст и проверьте, что реплика действительно относится к этому месту. Номер строки полезен вместе с версией: после следующего изменения он может указывать на другой код. Когда возможно, используйте ссылку на конкретную ревизию средствами вашего хранилища.
Расшифровка фиксирует речь, а не содержимое экрана. Из фразы «в этом условии» нельзя получить точный оператор, имя переменной или путь файла. Если запись только звуковая и контекст не удаётся восстановить, оставьте поле «место кода: уточнить». Не вставляйте придуманный фрагмент, чтобы карточка выглядела законченной.
Разделяйте наблюдение и объяснение. «При пустом списке показано такое сообщение» — наблюдение, если оно действительно проверено. «Вероятно, условие неверно» — гипотеза. Зафиксируйте входные данные, ожидаемый и фактический результат, когда они были названы или проверены. Если тест не запускали, честная запись — «требует воспроизведения», а не «ошибка подтверждена».
Сформулируйте полезный комментарий
Пишите о коде и поведении, а не о качествах автора. Вместо «ты опять всё усложнил» опишите конкретную сложность чтения или проверки и её причину. Полезное замечание отвечает на вопросы: где это находится, что вызывает проблему, почему это важно и по какому признаку изменение можно проверить.
Не обязательно диктовать единственную реализацию. Если важен результат, сформулируйте ожидаемое поведение и предложите вариант как вариант. Если речь о личном предпочтении, обозначьте необязательность. Для существенной проблемы объясните причину: комментарий «переименовать» без контекста не помогает понять, что именно должно стать яснее.
Добавляйте способ проверки по масштабу замечания. Для изменения поведения это может быть конкретный вход и ожидаемый результат; для документации — проверка термина и ссылки; для названия — понятность в месте использования. Не пишите «все тесты прошли», если обсуждение содержит лишь предложение их запустить. У протокола и фактического результата проверки разные источники.
Согласуйте итог и сохраните историю
После разговора перенесите важные выводы в место, где команда рассматривает изменение. Укажите, какие замечания согласованы, какие остались вопросами и какие сняты после объяснения. Ответственный и срок появляются только при явной договорённости; протоколист не назначает их по интонации или должности участника.
Если разговор перешёл к архитектуре проекта и результат выходит за рамки текущего изменения, сохраните отдельное решение по шаблону журнала решений и свяжите его с обсуждением. Это позволяет не терять причину выбранного подхода и не смешивать её с небольшим замечанием к строке кода.
При следующей ревизии отметьте, куда перенеслось исправление и как оно проверено. Закрывайте замечание на основании результата, а не самого факта нового коммита. Сохраняйте исходную формулировку, уточнение и итог: тихая замена текста может скрыть, что вопрос сначала считался ошибкой, а затем был снят. Расшифровка помогает восстановить ход разговора, но сама по себе не является техническим одобрением изменения.
Из «здесь падает» в карточку проверки
Учебный пример: команда обсуждает обработку пустого списка. В записи есть реплика «тут при пустом списке, кажется, падает», но нет точного имени функции и демонстрации запуска. Пример условный: реальный репозиторий и тесты не проверялись.
| Реплика из учебного обсуждения | Запись в протоколе | Что ещё проверить |
|---|---|---|
| «Здесь пустой список ломает ответ» | Гипотеза: проверить поведение при пустом списке | Версия, место и воспроизведение |
| «Переименуй, непонятно что внутри» | Предложение: название должно пояснять содержимое | Согласована ли обязательность |
| «Это же уже обсудили» | Найти предыдущее решение и его причину | Относится ли оно к текущей ревизии |
| «После правки всё нормально» | Заявление участника о результате | Чем и на какой версии проверено |
Протоколист сохраняет время реплики, помечает её как гипотезу, затем просит уточнить место кода и способ воспроизведения. После фактической проверки карточка получает наблюдение и ожидаемый результат либо отметку «не воспроизведено». До этого вывод о подтверждённой ошибке преждевременен.
Карточка замечания по записи
Изменение / обсуждаемая ревизия: Дата / время реплики в записи: Цитата или явно обозначенный пересказ: Файл / функция / контекст (сверено по коду): Тип: вопрос / гипотеза / согласованное исправление / предложение Наблюдение и источник: Причина, почему это важно: Ожидаемое поведение или критерий: Предложенный вариант (если есть): Способ проверки: Что не проверено / что уточнить: Обязательность согласована: Ответственный и срок (только по договорённости): Результат проверки / версия после изменения: Итог: открыто / исправлено / снято / перенесено
Частые вопросы
Можно ли отправить расшифровку как готовый код-ревью?
Она сохраняет разговор, но не подтверждает версию, точное место кода и результат проверки. Сначала выделите замечания, сверяйте контекст и обозначьте неопределённость.
Как восстановить имя функции, если его плохо распознало?
Сверьте звук и обсуждавшуюся версию кода. Если несколько вариантов возможны, запросите уточнение. Не подменяйте услышанное подходящим на вид идентификатором.
Номер строки достаточно точный?
Он зависит от ревизии. Сохраните версию и контекст: файл, функцию или устойчивый фрагмент. После изменения заново проверьте привязку.
Каждое предложение обязательно исправлять?
Обязательность определяет договорённость команды. Отделите требования от вопросов, гипотез и необязательных улучшений, не назначая приоритет по тону голоса.
Кто может объявить изменение принятым?
Это определяется процессом проекта и полномочиями участников. Протокол записи не создаёт одобрение и не заменяет требуемые проверки.