Код-ревью

Что такое код-ревью

Код-ревью (code review) — это проверка изменений другим человеком до слияния: он читает разницу, пишет замечания и вопросы, а автор их учитывает. На GitHub ревью делают прямо в pull request, на вкладке Files changed. В уроке вы проведёте ревью на проекте «Визитка»: оставите замечания к строкам, предложите правку и ответите на неё.

В прошлом уроке вы сами создали и сами слили pull request. Это путь без проверки, а смысл PR именно в ней: пока изменение не влито, его можно поправить, и никто не пострадает.

Простыми словами

Вы написали важное письмо. Прежде чем отправить, просите прочитать его коллегу: он увидит опечатку, которую вы уже не замечаете, и спросит, что имелось в виду в запутанной фразе. Код-ревью делает то же самое: даёт свежий взгляд и заодно показывает команде, что и зачем меняется.

Как писать замечания

Главная проблема ревью не технические ошибки, а тон. Замечание читает живой человек, который потратил время. Четыре правила:

• говорите о коде, а не о человеке: «эта строка не работает», а не «вы ошиблись»;
• вместо приказа задавайте вопрос или предлагайте вариант;
• объясняйте, почему вы так думаете;
• отмечайте и хорошее: короткое «здорово, что вынесли в отдельный раздел» тоже комментарий.

Ревью в интерфейсе GitHub

Допустим, коллега открыл pull request, а вы его ревьюер. Вот что вы делаете на GitHub:

1. Откройте pull request и перейдите на вкладку Files changed.
2. Наведите курсор на нужную строку и нажмите синий значок комментария. Чтобы прокомментировать несколько строк, выделите их по номерам: нажмите на первый номер и, удерживая Shift, на последний.
3. Напишите замечание. Если хотите предложить конкретную замену, нажмите значок Suggestion над полем комментария и отредактируйте текст внутри появившегося блока.
4. Нажмите Start a review. Для следующих комментариев кнопка будет называться Add review comment.
5. Закончив, нажмите Review changes над изменённым кодом, напишите общий итог, выберите вердикт и нажмите Submit review.

Кнопка Suggestion вставляет в комментарий особый блок. Он выглядит так (внутри — новый текст строки):

Предлагаю «Знаю»: звучит увереннее.

```suggestion
    <p>Знаю HTML и CSS, учу Git.</p>
```

GitHub покажет такой блок автору не как текст, а как красно-зелёную разницу с кнопкой применения. Писать три обратных кавычки вручную не нужно, значок всё вставит сам.

Три вердикта при отправке ревью:

Как отвечать на ревью

Автор читает вкладку Conversation, где видны замечания, и по каждому делает одно из трёх: принимает предложение, исправляет сам, либо объясняет, почему оставляет как есть.

• Принять предложение. Под комментарием с блоком suggestion нажмите Commit suggestion, введите короткое сообщение коммита и подтвердите кнопкой Commit changes. GitHub сам сделает коммит в ветку PR, а автор замечания станет соавтором коммита. Предложений несколько? Нажимайте Add suggestion to batch на каждом и затем Commit suggestions: получится один общий коммит.
• Исправить сам. Поправьте код у себя, закоммитьте и сделайте git push. Новый коммит попадёт в тот же PR.
• Не согласиться. Ответьте в той же ветке комментариев: добавьте ещё один комментарий под существующим, аргументы не обидны, если они по делу.

Когда замечание учтено, нажмите под ним Resolve conversation: ветка комментариев свернётся и станет ясно, что осталось. Закрыть её может автор PR или любой, у кого есть право записи в репозиторий.

Ловушка: коммит на GitHub и коммит у вас

Если вы приняли предложение кнопкой Commit suggestion, новый коммит появился на GitHub, а у вас на компьютере его нет. Попробуете запушить свой коммит, не забрав чужой, — и Git откажет:

$ git push
To https://github.com/alex-ivanov/portfolio.git
 ! [rejected]        feature/about-skills -> feature/about-skills (fetch first)
error: failed to push some refs to 'https://github.com/alex-ivanov/portfolio.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. If you want to integrate the remote changes, use
hint: 'git pull' before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Git говорит: на GitHub в этой ветке есть работа, которой нет у вас. Это то же сообщение, что вы видели, когда работали с двух мест. Лечение: git pull, затем git push. А лучше делать git pull в ветке PR до новой правки:

$ git pull
From https://github.com/alex-ivanov/portfolio
   26e1229..5da84fd  feature/about-skills -> origin/feature/about-skills
Updating 26e1229..5da84fd
Fast-forward
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Хороший pull request

Ревью проходит легко, когда PR удобно читать. Пара правил, которые экономят время всей команде:

• Маленький. Лучше несколько небольших PR, чем один на сотню файлов: большие просматривают по диагонали.
• Одна задача. Исправили ссылку и заодно переделали стили? Это два PR. Так проще проверять и откатывать.
• Понятное описание. Что сделано, зачем, как проверить. Если правка видна на странице, опишите словами, что именно изменилось.
• Сначала проверьте сами. Откройте Files changed в своём PR до просьбы о ревью: часто глаз сам цепляется за забытую отладочную строку.

Практика у себя

Мы моделируем команду: вы будете и автором, и ревьюером. Если есть друг с аккаунтом GitHub, попросите его провести ревью по этому плану.

1. В терминале: git switch main, git pull, git switch -c feature/about-skills.
2. В index.html в разделе «Обо мне» после абзаца «Учусь программировать и делаю свой первый сайт.» добавьте две строки: <p>Умею: HTML, CSS, немного Git.</p> и <p>Ищу первую работу или стажировку.</p>.
3. Закоммитьте и отправьте: git add index.html, git commit -m "Добавить навыки в раздел «Обо мне»", git push -u origin feature/about-skills.
4. На GitHub откройте PR кнопкой Compare & pull request (это будет #2), заполните заголовок и описание, нажмите Create pull request.
5. Станьте ревьюером: откройте Files changed, наведите курсор на строку «Умею: ...», нажмите синий значок, затем Suggestion, замените строку внутри блока на <p>Знаю HTML и CSS, учу Git.</p> и нажмите Start a review.
6. К строке «Ищу первую работу...» оставьте обычный комментарий: «Давайте вынесем эту строку в отдельный PR, здесь речь про навыки» и нажмите Add review comment.
7. Нажмите Review changes, напишите «Две мелочи, остальное хорошо», выберите Comment и нажмите Submit review.
8. Снова станьте автором: на вкладке Conversation под первым замечанием нажмите Commit suggestion, затем Commit changes.
9. У себя выполните git pull: Git перемотает ветку на один коммит. Удалите из index.html строку «Ищу первую работу...», закоммитьте (git commit -am "Убрать строку про работу") и сделайте git push.
10. На GitHub нажмите Resolve conversation под обоими замечаниями. Слейте PR (Merge pull request, Confirm merge), нажмите Delete branch, а затем у себя сделайте git switch main, git pull, git branch -d feature/about-skills, git fetch --prune.

Ожидаемый результат: в git log --oneline видны три коммита ветки (первый ваш, замена «Умею» на «Знаю» и «Убрать строку про работу») и сверху коммит слияния Merge pull request #2 from alex-ivanov/feature/about-skills.

Проверьте себя

• В PR #2 на вкладке Commits три коммита, на вкладке Conversation оба замечания свёрнуты как решённые.
• git status на main чистый, строки «Ищу первую работу...» в index.html нет.
• Вы знаете, почему кнопка Approve недоступна в вашем собственном PR.
• Вы можете назвать три вердикта ревью и когда выбирать каждый.
• Вы знаете, что делать, если git push ответил (fetch first) в ветке PR.

Частые ошибки

Огромный PR. Двести строк в десяти файлах никто читает внимательно. Делите работу на отдельные PR по одной задаче.

Новый PR вместо нового коммита. Получив замечания, не открывайте второй PR: допишите коммит в ту же ветку, и старый обновится с историей обсуждения.

Комментарии не отправлены. Ревьюер нажал Start a review, но забыл Review changes и Submit review: автор ничего не видит. Черновики заметны только их автору.

Спор в комментариях. Если после трёх ответов вы друг друга не понимаете, дальше переписываться бесполезно: лучше созвониться или поговорить, а итог записать в PR.

Принять предложение и пушить поверх. После Commit suggestion сначала git pull, потом работа, иначе (fetch first).

Что важно запомнить

• Код-ревью — проверка PR другим человеком: комментарии к строкам на вкладке Files changed и вердикт через Review changes (Comment, Approve, Request changes).
• Замечания о коде, а не о человеке: вопрос вместо приказа, с объяснением.
• Предложенную правку принимают кнопкой Commit suggestion; после неё у себя нужен git pull.
• Исправления идут новыми коммитами в ту же ветку: PR обновляется сам. Решённое закрывают через Resolve conversation.
• Свой PR одобрить нельзя; PR должен быть маленьким и про одну задачу.

Мы обсудили, как проверять изменения. Но откуда берутся сами задачи? В командах их записывают в issues — карточки задач на GitHub, которые связываются с pull request. Этим займёмся в следующем уроке.