Como usar as funções de comentário e revisão no GitHub (Introdução à revisão de código)

No artigo anterior, você deu o primeiro passo para contribuir com o projeto de outra pessoa usando `Fork` e `Pull Request`. No entanto, o desenvolvimento não termina apenas enviando um Pull Request. É aqui que começa a verdadeira essência do desenvolvimento em equipe: a revisão de código.

A revisão de código é o processo em que outros desenvolvedores verificam o código que você escreveu e fornecem feedback. Isso permite encontrar bugs mais cedo, aprender melhores maneiras de escrever código e melhorar a qualidade geral do código da equipe. Neste artigo, explicaremos detalhadamente como se comunicar de forma eficaz no GitHub e como usar as funções de comentário e revisão para uma revisão de código eficiente.

O básico da revisão de código: Comunicação em Pull Requests

O local central para a revisão de código é a página do Pull Request que você criou. Esta página agrega todas as informações sobre suas alterações, e a comunicação aqui influencia a qualidade do projeto.

As funções de revisão do GitHub são divididas em duas categorias principais:

• Comentário (Comment): Uma função para postar perguntas ou opiniões livremente em linhas de código específicas ou em todo o Pull Request.
• Revisão (Review): Uma função para avaliar formalmente todas as alterações e indicar a intenção de "Aprovar (Approve)", "Apenas comentar" ou "Solicitar alterações (Request changes)".

Usar esses dois recursos de forma seletiva permite uma comunicação tranquila.

Como usar a função de comentário especificamente

Primeiro, vamos ver a função de comentário, que pode ser usada facilmente.

1. Comentários em todo o Pull Request

Se você quiser fazer perguntas gerais sobre toda a alteração ou expressar agradecimentos, use a seção de comentários na parte inferior da página do Pull Request. Ela está localizada na parte inferior da guia "Conversation".

[Imagem: Captura de tela do campo de entrada de comentários na parte inferior da página do Pull Request]

Basta inserir sua mensagem na área de texto e clicar no botão "Comment" para postar. Você também pode notificar (mencionar) uma pessoa específica digitando `@nome_de_usuario`.

2. Comentários em linhas de código específicas

A função mais usada na revisão de código é o comentário por linha. É ideal para fazer apontamentos específicos, como "O nome desta variável não poderia ser mais claro?".

1. Na página do Pull Request, clique na guia "Files changed".
2. Uma lista de arquivos alterados será exibida, então passe o cursor do mouse à esquerda da linha de código que você deseja comentar.
3. Um ícone azul "+" aparecerá, clique nele.
4. Uma caixa de texto será exibida, digite seu comentário e clique no botão "Start a review".

[Imagem: Adicionando um comentário a uma linha específica na aba "Files changed"]

Neste ponto, seu comentário ainda está no estado "Pendente (Pending)". É comum reunir vários apontamentos e, em seguida, enviá-los todos juntos como uma revisão final.

3. Função de sugestão de alteração (Suggestion)

Se você quiser propor um código específico, como "Seria melhor reescrever desta forma", clique no ícone "Insert a suggestion" (um símbolo como `+/-`) acima da caixa de comentários. Um bloco de código será inserido, permitindo que você escreva sua sugestão de correção diretamente.

[Imagem: Propondo uma sugestão de alteração de código usando a função "Insert a suggestion" na caixa de comentários]

Usar esta função é muito conveniente porque o criador do Pull Request pode aplicar sua sugestão ao código com um único clique.

Enviando uma revisão: Aprovar ou solicitar alterações

Depois de acumular vários comentários, o próximo passo é enviá-los todos juntos como uma "revisão". Clique no botão "Review changes" exibido no canto superior direito da tela.

[Imagem: Apontando para o botão "Review changes"]

As três opções a seguir serão exibidas:

• Comment: Escolha esta opção se você não quer aprovar nem solicitar alterações, mas apenas deixar um comentário como feedback. Use para "perguntas rápidas" ou "opiniões pessoais".
• Approve: Uma expressão de aprovação que significa "Esta alteração é ótima! Sem problemas, pode fazer o merge".
• Request changes: Uma solicitação de alteração que significa "Esta alteração precisa de correção. Por favor, corrija os pontos que indiquei antes de fazer o merge".

[Imagem: Janela modal mostrando as três opções ao enviar uma revisão (Comment, Approve, Request changes)]

Escolha a opção apropriada, escreva um comentário de resumo se necessário e clique no botão "Submit review". Sua revisão será formalmente enviada, e o criador do Pull Request receberá uma notificação.

Respondendo a uma revisão: Corrigindo e fazendo push das alterações

Agora, vamos ver como proceder quando você é o criador do Pull Request e recebe uma revisão de outra pessoa.

Passo 1: Verifique o conteúdo do comentário e discuta
Primeiro, agradeça pelo feedback recebido. Se houver algo que você não entendeu, responda e pergunte. Toda a comunicação fica registrada no Pull Request.

Passo 2: Corrija o código com base nos apontamentos
Se você concorda com os apontamentos do revisor, corrija o código em seu computador local. Seria ainda mais profissional se você trabalhasse em um novo branch, como `fix-review-comments`.

Passo 3: Faça push dos commits adicionais
Após a correção, crie um novo commit e faça o push para o branch de origem do Pull Request (ex: `fix-typo-in-readme`).

git commit -m "Reflect review comments"

git push origin fix-typo-in-readme

Ao fazer o push de um novo commit, a alteração é automaticamente refletida no Pull Request. Não há necessidade de criar um novo Pull Request.

Passo 4: Resolva as conversas concluídas
Depois de lidar com todos os apontamentos, clique no botão "Resolve conversation" abaixo de cada comentário para marcar a conversa como resolvida. Isso torna claro quais apontamentos já foram tratados.

[Imagem: O botão "Resolve conversation" é pressionado e a conversa é recolhida]

Quando todas as conversas forem resolvidas e você receber um novo "Approve" do revisor, finalmente será hora de fazer o merge.