1. Diagnóstico do código: entender o contexto, arquitetura e responsabilidades

Antes de recomendar mudanças, mergulho no contexto do PR para evitar propostas catalisadoras de retrabalho. A prática recomendada envolve alinhar compreensão com a arquitetura, contratos e objetivos de negócio.

• Identifique o escopo: módulos afetados, interfaces públicas, responsabilidades de cada classe.
• Mapeie dependências: bibliotecas, serviços externos, contratos de APIs e schemas de dados.
• Valide contratos de API: tipos de retorno, formatos de dados, validações esperadas pelo consumidor.
• Avalie padrões de design: coesão, acoplamento, boundaries claros entre componentes.
• Verifique a documentação do PR: objetivo, cenários cobertos, impactos conhecidos e critérios de aceitação.

Neste passo, a clareza da justificativa da mudança é tão importante quanto a mudança em si. Um PR bem descrito evita discussões repetitivas e acelera a evolução do código.

2. Desempenho, complexidade e escalabilidade

Revisões avançadas não devem se limitar a “funciona”. Elas devem considerar desempenho, escalabilidade e uso consciente de recursos. Abaixo estão diretrizes para conduzir essa avaliação.

• Estimativa de complexidade: analise loops aninhados, recursão profunda e operações fora de padrão que afetam o tempo de execução.
• Avalie alocações e memória: crie hipóteses sobre picos de memória e vazamentos potenciais.
• Copie estratégias de caching com cautela: validade de cache, invalidação, coerência entre dados locais e remotos.
• Observabilidade: adicione métricas úteis, tracing e logs suficientes sem expor sensíveis.
• Testes de desempenho: verifique cenários de carga relevantes e pense em limites de escalabilidade.

Exemplos práticos incluem evitar consultas redundantes, reduzir operações caras dentro de loops e usar padrões de streaming quando apropriado.

3. Segurança, confiabilidade e limites de entrada

A revisão deve incluir verificações explícitas de segurança e robustez. Falhas comuns costumam emergir quando as validações não são profundas o suficiente ou quando erros são mal tratados.

• Validação de entradas: checagem de tipos, formatos, limites de tamanho e sanificação de dados de usuários.
• Tratamento de erros: respostas seguras, mensagens mínimas ao usuário e logs detalhados para diagnósticos internos.
• Gestão de segredos: evitar exposição de chaves, tokens ou credenciais; preferir variáveis de ambiente.
• Confiabilidade: fail-fast, tratamento de exceções previsíveis e circuit breakers quando dependências falham.
• Condições de corrida e concorrência: sincronização adequada, atomicidade de operações críticas, uso de locks com cuidado.

Segurança não é adicional; é parte intrínseca da qualidade do código. Pequenos ajustes podem prevenir problemas graves em produção.

4. Colaboração, comunicação e critérios de aceite

O valor de uma revisão está na qualidade da comunicação e na clareza de critérios de aceitação. Estabelecer uma abordagem padronizada facilita a tomada de decisão coletiva e reduz ciclos de feedback.

• Checklist de revisão: leia, entenda, questione, proponha melhoria, valide com testes e documentação.
• Critérios de aceitação: Definição de Done explícita, cobertura de testes, impacto mínimo no comportamento existente.
• Documentação das mudanças: explique o “porquê” e o “como” da modificação, com referências a decisões arquiteturais.
• Comunicação respetuosa: baseie-se em fatos, evite julgamentos pessoais, encoraje discussões técnicas construtivas.
• Colaboração efetiva: incentive revisões pares, registre decisões-chave e mantenha um histórico de aprendizados.

Para ilustrar como aplicar esse conjunto de práticas, veja um exemplo de código que costuma aparecer em revisões e como avaliá-lo com profundidade.

// Exemplo a ser revisado (JavaScript)
async function fetchUser(id) {
  const res = await fetch('/api/users/' + id);
  if (res.ok) {
    return res.json();
  }
  return null;
}

Como melhorar: introduza timeout, trate erros com respostas coerentes, valide parâmetros, trate casos de falha de forma determinística e registre métricas relevantes. Sempre questione se a função está pronta para cenários do mundo real antes de aprová-la.