Para que serve a revisão de código

Um tópico, num curso com outras coisas para ensinar

A aula de abertura de "Pull requests" dá à revisão de código um tópico entre quatro: "um segundo par de olhos pega bugs, sugere abordagens melhores, e espalha conhecimento sobre a base de código pelo time". Aquele curso tinha sete aulas de mecânica do GitHub para cobrir: a visão de diff, comentários inline, aprovações, proteção de branch e três estratégias de merge. Nunca sobrou espaço para perguntar o que torna o comentário de um revisor digno de leitura, ou o que um revisor deve procurar. Esse é o trabalho deste curso.

Não é repetir cliques

Este curso não repete abrir um PR, deixar um comentário inline, resolver uma conversa ou escolher uma estratégia de merge. "Pull requests" já cobriu tudo isso. Este curso supõe que você sabe fazer isso e faz outra pergunta. Você pode deixar qualquer comentário, então quais valem a pena, e como decidir?

As práticas de engenharia do Google, a fonte em que este curso se apoia

Boa parte do que vem a seguir sai da documentação de práticas de engenharia que o Google publica, as orientações sob as quais os engenheiros dele revisam código. O padrão para aprovar uma mudança diz: "revisores deveriam favorecer aprovar uma CL uma vez que ela está num estado que definitivamente melhora a saúde geral do código do sistema em que se trabalha, mesmo que a CL não esteja perfeita". Perfeição não é a régua. A mesma página diz que "não existe código 'perfeito'", só código melhor.

O que este curso cobre

A aula 2 olha o que a CI pega neste app e o que ela deixa para uma pessoa, a partir do .github/workflows/ci.yml do projeto. A aula 3 trata de quão sério é um comentário, nit contra opcional contra obrigatório, com os rótulos que a documentação do Google define. A aula 4 é sobre tom: comentar o código, não a pessoa. A aula 5 cobre o trabalho do próprio revisor, o tempo de resposta e qual dos três veredictos escolher, indo além da mecânica de approvals-checks-and-branch-protection. A aula 6 é sobre receber feedback, indo além do "responda com seu raciocínio" de responding-to-review-feedback para separar discordância de confusão. A aula 7 junta tudo num diff pequeno.

Onde isso deixa você

No fim, "deixar uma boa revisão" quer dizer mais que "ler o diff e dizer alguma coisa". Quer dizer saber o que vale apontar, com que intensidade, e como dizer sem que soe como ataque. Também quer dizer decidir, quando todos os comentários estiverem lá, se a mudança está pronta.