Exercícios de revisão de código: como usar a revisão por pares para desenvolver análises e julgamento técnico.

Um desenvolvedor abre um pull request que adiciona um cálculo de desconto a um serviço de checkout. Os testes passam e o diff é curto. Um revisor aprova em dois minutos com um "OK". Três meses depois, um colega precisa alterar a mesma função e descobre que ela mistura regras de precificação, arredondamento e acesso ao banco de dados em um único lugar. Ninguém consegue afirmar com certeza o que é permitido fazer.

Este é um cenário ilustrativo, não um incidente documentado. Ele mostra o que a revisão de código por pares deve produzir quando funciona como uma atividade de aprendizado: um revisor capaz de identificar uma mudança plausível, reconhecer a preocupação que ainda não é um bug e explicá-la de forma que o autor possa agir.

Este guia destina-se a líderes de capacitação em engenharia e gerentes de engenharia. Ele mostra como projetar exercícios de revisão de código que desenvolvem essa habilidade propositalmente, em vez de esperar que os revisores a identifiquem aleatoriamente. Abrange o problema de desempenho, as lacunas a serem diagnosticadas, como estruturar a preparação e a prática, um exemplo prático e como verificar se a habilidade é aplicável em revisões reais. Peça a engenheiros seniores que validem cada caso, defeito e critério antes de você utilizá-lo.

O que são exercícios de revisão de código?

Exercícios de revisão de código são tarefas práticas estruturadas nas quais um desenvolvedor revisa uma alteração preparada, explica o que encontrou e por que isso é importante, e recebe feedback sobre a qualidade dessa explicação. Eles são diferentes das revisões que sua equipe faz diariamente. A alteração é escolhida com antecedência, os problemas nela contidos são conhecidos e o objetivo é aprimorar o revisor, em vez de simplesmente implementar a alteração.

Fatos rápidos

1. Descreva o problema de desempenho.

Comece pela tarefa, em uma frase: dada uma alteração, o revisor explica o que encontrou, por que isso é importante e o que o autor poderia fazer a respeito. "Explica" é a palavra-chave. Identificar um problema é metade da habilidade. Expressá-lo de forma que um colega com uma visão diferente possa entendê-lo, ponderá-lo e agir é a outra metade.

Pesquisas sobre revisão de código moderna apoiam a ideia de ir além da simples busca por bugs. Em um estudo na Microsoft, Bacchelli e Bird observaram, entrevistaram e pesquisaram desenvolvedores e gerentes. Eles descobriram que encontrar defeitos ainda era a principal motivação para a revisão, mas que as revisões eram menos focadas em defeitos do que as pessoas esperavam. Elas também proporcionaram outros benefícios, como compartilhamento de conhecimento, conscientização da equipe e soluções alternativas, e os pesquisadores descreveram a compreensão do código e das alterações como o aspecto fundamental da revisão.Bacchelli e Bird, ICSE 2013Trata-se de um estudo sobre as equipes de uma empresa, portanto, use-o como um incentivo para projetar com foco na compreensão, e não como uma forma de avaliar as suas próprias equipes.

O padrão de revisão publicado pelo Google aponta na mesma direção. Ele orienta os revisores a priorizar a aprovação de uma alteração somente quando ela comprovadamente melhorar a integridade geral do código, mesmo que não seja perfeita, e afirma que a revisão pode ensinar algo novo aos desenvolvedores, portanto, comentários que contribuam para o aprendizado são bem-vindos.Práticas de Engenharia do GoogleAmbas as fontes descrevem a revisão como um espaço onde o julgamento é exercido e transmitido. É isso que seus exercícios devem praticar.

2. Diagnosticar as lacunas de aprendizagem e de contexto

Compare a tarefa com o que o seu programa atual pratica e avalia.

1. A prática atual utiliza a tarefa real? Se os novos revisores aprendem lendo um guia de estilo e depois revisando pull requests reais, eles praticam em trabalho concreto, sem margem para erros. Se a avaliação for um teste sobre etiqueta de revisão, ela mede a memorização das regras, não a capacidade de aplicá-las a uma alteração.
2. Qual é a demanda cognitiva? Na taxonomia de Bloom revisada, julgar se um projeto é sólido e ponderar suas vantagens e desvantagens se enquadra nos níveis de análise e avaliação, enquanto propor uma estrutura melhor atinge o nível de criação. Se seus exercícios perguntam apenas "o que este código faz?", eles param no nível de compreensão. Nosso guia para Alinhar as atividades de aprendizagem à Taxonomia de Bloom Mostra como adequar a atividade ao nível.
3. Existe algo além da habilidade que está atrapalhando? Verifique o tempo de revisão, as ferramentas, a responsabilidade e as normas da equipe. Se os revisores tiverem cinco minutos por solicitação de pull request, nenhum exercício resultará em uma explicação ponderada. Se os autores interpretarem cada comentário como uma crítica, os revisores suavizarão suas conclusões até que não digam nada. Informe essas causas às pessoas que podem resolvê-las.

3. Preparação, prática e feedback do projeto

Atribua uma tarefa diferente a cada etapa.

Preparação. Verifique o que os revisores precisam antes de começar: a lista de verificação de revisão da equipe, os princípios de design nos quais ela se baseia e como interpretar as diferenças (diff) nas suas ferramentas. Mantenha o processo em seu próprio ritmo e seja breve. Uma verificação de conhecimento prévio apenas confirma os pré-requisitos e não comprova que alguém esteja apto a revisar.

Prática. Use alterações pré-configuradas com um pequeno número de preocupações predefinidas de diferentes tipos: um bug de correção, um problema de manutenção como as responsabilidades mistas no exemplo inicial, um nome pouco claro ou um teste ausente e algum código que esteja correto. Peça ao revisor para escrever o comentário que deixaria, classificar as preocupações e dizer quais informações adicionais ele gostaria de obter. A lição prática da CodeRefinery mostra o formato: as pessoas abrem uma solicitação de pull request contendo um pequeno erro de digitação e um erro maior e, em seguida, a revisam como um colega (CodeRefinery, Praticando revisão de códigoConstrua o seu a partir de sua própria base de código para que as convenções e as compensações sejam reais.

Feedback. Relacione isso às decisões tomadas pelo revisor. "Você notou o problema de arredondamento, mas seu comentário dizia 'isso parece errado' sem especificar qual entrada causa o problema" é mais útil do que "encontrei 2 de 4".

Entrada ao vivo ou revisão assíncrona? A contribuição em tempo real agrega mais valor quando uma questão é ambígua e os revisores aprendem ao ouvir um engenheiro sênior explicar por que a levantariam ou a deixariam de lado. A revisão assíncrona é suficiente para comparar comentários com uma revisão especializada e anotada.

4. Analise um exemplo realista.

Exemplo ilustrativo. Um gerente de engenharia deve validar o caso e os critérios de resposta antes de utilizá-los.

O caso. Uma alteração adiciona um cálculo de desconto a um serviço de finalização de compra. Ela passa nos testes. Em uma função, aplica descontos percentuais e fixos, arredonda o resultado, grava no banco de dados e envia um evento. Possui um teste, para um único desconto percentual.

A tarefa. O revisor escreve os comentários que deixaria, classifica suas preocupações e indica o que precisaria saber antes de aprovar.

Uma primeira tentativa. "Parece tudo bem, o teste passou. Talvez seja melhor dividi-lo?" O revisor notou algo, mas não disse o quê, por que é importante ou o que fazer. O autor não pode tomar nenhuma providência com base nisso.

Feedback e tentativa novamente. O facilitador pergunta: o que uma futura alteração nesta função poderia comprometer? O que você pediria ao autor para adicionar antes de aprovar? A nova tentativa solicita um comentário específico sobre cada preocupação, com a justificativa e uma sugestão.

Uma tentativa mais robusta. "A função aplica dois tipos de desconto, arredonda, salva e publica um evento, então uma mudança no arredondamento poderia alterar o que armazenamos e o que publicamos simultaneamente. Eu pediria que as regras de precificação fossem movidas para uma função pura que pudéssemos testar separadamente. O único teste cobre apenas um desconto percentual. Eu pediria um desconto fixo e um pedido que reduza o total a zero. Não tenho certeza se o evento deve ser disparado quando o total for zero, então eu perguntaria ao autor." Observe que este comentário nomeia a preocupação, apresenta o motivo, faz uma sugestão concreta e declara o que o revisor não sabe.

5. Avaliar a capacidade e planejar a transferência.

A comprovação de capacidade consiste no desempenho em uma nova mudança que o avaliador não tenha observado. Avalie a precisão das conclusões e a utilidade da explicação. Uma rubrica simples utiliza uma escala de 0 a 2 para cada critério:

Critérios de avaliação: 0 significa ausente ou sem justificativa, 1 significa parcial com omissões relevantes e 2 significa completo e justificado de acordo com os critérios acordados. Defina erros críticos separadamente, por exemplo, aprovar uma alteração com risco de perda de dados, para que uma boa pontuação geral não possa mascarar um erro crítico. Adapte os critérios com o gerente de engenharia; esta rubrica é uma proposta inicial, não um padrão de prontidão validado. Para mais informações sobre como avaliar a justificativa, consulte nosso guia. Projetando práticas interativas com feedback útil.

Planeje a transferência. Após o exercício, verifique uma amostra das avaliações reais do avaliador algumas semanas depois, usando os mesmos critérios. Compare com uma linha de base coletada antes do treinamento e defina a população e o cronograma antecipadamente. Analise outras mudanças que ocorreram no mesmo período, como uma nova ferramenta de avaliação ou uma alteração na equipe, antes de creditar os exercícios.

6. Execute o exercício ao vivo ou no seu próprio ritmo com o AhaSlides.

Você pode realizar o exercício em um workshop ou deixar que os revisores o façam individualmente. Em uma sessão ao vivo, mostre a alteração preparada e use slides interativos para a discussão:

1. Escolha resposta Para a pergunta "qual preocupação você levantaria primeiro?", com as preocupações sugeridas como opções, mostre a distribuição das preocupações antes de revelar sua própria classificação.
2. Final em aberto Para "escreva o comentário que você deixaria", os revisores podem comparar sua redação com a de outros, e é aí que a habilidade de explicação se destaca.
3. Escala de classificação para "quão grave é isso?", para que o grupo possa ver onde os julgamentos divergem e discutir o porquê.

Para os revisores que não puderem comparecer, a mesma sequência pode ser usada em ritmo próprio, com a revisão especializada e comentada exibida após cada resposta. Considere qualquer afirmação sobre execução de código, integrações ou recursos de IA como não confirmada até que você a tenha testado com seu próprio material.

Se você também treina revisores em código escrito por IA, consulte nosso guia complementar sobre Treinamento de revisão de código gerado por IAAquele post trata da auditoria de resultados gerados. Este aqui aborda como as pessoas revisam o trabalho umas das outras e como explicam suas conclusões.

Restrições que podem permanecer

• Hora da revisão. Um comentário ponderado leva mais tempo do que "LGTM", e os prazos pressionam para a versão curta.
• Normas da equipe. Se o feedback for interpretado como uma crítica pessoal, os avaliadores irão suavizar ou omitir suas conclusões.
• Cobertura do caso. Um exercício demonstra alguns tipos de preocupação. Uma nota não descreve o julgamento geral de um avaliador.
• Transferência. O desempenho em uma oficina não é o mesmo que o desempenho em uma fila movimentada, portanto, verifique também avaliações reais.

Informe esses problemas aos patrocinadores com antecedência e planeje correções separadas. Os exercícios melhoram a capacidade do revisor de observar e explicar os problemas. Eles não criam o tempo necessário nem definem as normas.

Perguntas frequentes

O que são exercícios de revisão de código?

São tarefas práticas preparadas nas quais um desenvolvedor revisa uma alteração com problemas conhecidos, escreve os comentários que faria e recebe feedback sobre a precisão e utilidade. O objetivo é aprimorar a habilidade do revisor, não implementar a alteração.

Como avaliar se o julgamento de um revisor melhorou?

Apresente uma nova alteração que eles ainda não viram e avalie as observações e a explicação de acordo com critérios predefinidos. Em seguida, verifique uma amostra de avaliações reais algumas semanas depois. Um questionário sobre as regras de avaliação apenas confirma os pré-requisitos.

A revisão de código por pares serve principalmente para encontrar erros?

Encontrar defeitos ainda é uma das principais motivações, mas um estudo da Microsoft descobriu que as revisões se concentravam menos em defeitos do que o esperado e também promoviam o compartilhamento de conhecimento e a conscientização da equipe. É importante desenvolver exercícios que recompensem tanto a explicação e a compreensão quanto a contagem de defeitos.

Por onde começar

Escolha um tipo de mudança que sua equipe revisa com frequência. Elabore a declaração de desempenho, peça a um engenheiro sênior para preparar uma mudança com três ou quatro preocupações iniciais e crie uma rubrica com três critérios, numa escala de 0 a 2, e uma lista de erros críticos. Teste com um pequeno grupo e, em seguida, compare as próximas revisões reais com a linha de base.

Para ver como um exercício de revisão pode ser realizado ao vivo com sua própria equipe e reutilizado posteriormente em seu próprio ritmo, explore o AhaSlides.