Code Review: O que reviewzar?

Introdução

Muito se fala sobre a importância de construir sistemas escaláveis, robustos e bem estruturados. Quando esse assunto surge, muitos pensam imediatamente na stack ou nas tecnologias de ponta usadas para desenvolver a aplicação.

No entanto, a “chave” para um sistema realmente sólido não está apenas nas decisões de arquitetura, mas também na rotina e na organização do desenvolvimento.

Pense no seu repositório como uma casa sendo mobiliada. Você tem um projeto arquitetônico, um design de interiores e, constantemente, novos móveis chegam. Para que a casa permaneça fiel ao planejamento, é preciso analisar se cada nova mobília faz sentido na composição, correto?

Da mesma forma funciona o processo de code review: um momento em que desenvolvedores avaliam o código de outros desenvolvedores para garantir que nada fora do padrão — ou com potencial de gerar problemas — entre na “casa”, ou melhor, no repositório.

Inspirado no **“The Code Review Pyramid”*, de Gunnar Morling, este artigo tem como objetivo discutir o processo de code review* e destacar algumas boas práticas.

Segundo o modelo apresentado na pirâmide, diferentes aspectos do código possuem níveis distintos de importância durante a revisão. A base da pirâmide representa os pontos que merecem maior atenção, pois são justamente aqueles que podem gerar impacto significativo e duradouro no projeto.

1. Semântica da API (API Semantics)

A base da pirâmide representa o ponto mais crítico. Erros aqui podem comprometer todo o projeto e custar muito caro para corrigir depois. É onde o revisor deve dedicar mais atenção.

Perguntas inspiradas na pirâmide:

1.1 Os nomes de métodos, endpoints e entidades fazem sentido?

Eles comunicam claramente o que fazem e seguem um padrão previsível?

1.2 A API é consistente?

• Evita múltiplas formas diferentes de fazer a mesma coisa?
• Segue o princípio do least surprise? (Nada surpreende o usuário/consumidor da API).

Api inconsistente:

GET /users          // retorna usuários
GET /usuario/123    // pega usuário por ID (mudou para "usuario")
POST /createUser    // cria usuário (verbo no nome)
DELETE /users?id=7  // id passado de forma diferente

user.save()
user.updateUser()
user.remove()

Api consistente:

GET    /users          // lista usuários
GET    /users/{id}     // pega usuário por ID
POST   /users          // cria usuário
DELETE /users/{id}     // deleta usuário

user.create()
user.update()
user.delete()

Uma API é consistente quando:

• usa nomes iguais para coisas iguais
• segue o mesmo padrão em todos os lugares
• evita “surpresas” para quem usa
• segue uma lógica clara e repetível
• endpoints/métodos retornam formatos previsíveis

1.3 O uso dos tipos está correto?

• Os tipos transmitem a intenção?
• Há clareza entre entradas, saídas e erros esperados?

1.4 A “contratação” da API é clara e previsível?

• Faz sentido em termos de uso real?
• Há mudanças desnecessárias em partes sensíveis como contratos públicos, logs, configuração ou eventos?
• A API é pequena o suficiente, porém grande o bastante para atender o necessário?

Contratação da API clara

Significa:

• os parâmetros são bem definidos
• os nomes dos campos são consistentes
• os tipos nunca mudam sem motivo
• o formato de resposta é previsível
• o status HTTP reflete corretamente o resultado
• mudanças são feitas de forma versionada (ex.: /v2/)

Contratação da API previsível

Significa:

• se eu chamar 10 vezes a mesma rota, sei exatamente o que esperar
• nada muda “do nada”
• cada endpoint segue padrões iguais

2. Semântica da Implementação (Implementation Semantics)

Aqui o foco é verificar se a lógica interna realmente resolve o problema da forma correta e sem introduzir complexidade desnecessária.

Perguntas essenciais:

2.1 O código faz o que deveria fazer?

Ele cumpre o requisito ou apenas “parece estar certo”?

2.2 Há casos de borda não tratados?

Ex.: valores nulos, limites, cenários incomuns.

2.3 Há bugs potenciais?

• Concorrência
• Exceções não tratadas
• Uso incorreto de dependências
• Falhas de performance

2.4 Há decisões estranhas ou inconsistentes?

O código surpreende o leitor ou quebra a lógica esperada do sistema?

2.5 O código é seguro?

Evita vulnerabilidades como:

• SQL injection
• erros de serialização
• falhas de autenticação/autorização

3. Documentação

A documentação adequada reduz dúvidas, acelera onboarding e ajuda revisores e futuros desenvolvedores.

Perguntas da pirâmide:

3.1 Novas features estão bem documentadas?

README, APIs, guias de uso, exemplos.

3.2 Os comentários são úteis e não redundantes?

Comentários devem explicar o porquê, não o como.

3.3 Documentação é clara e sem erros?

• Sem ambiguidade
• Sem erros graves de gramática
• Fácil de entender

4. Testes

Os testes garantem que a funcionalidade se mantém estável ao longo do tempo.

Perguntas inspiradas na pirâmide:

4.1 Todos os testes estão passando?

4.2 Novos casos foram razoavelmente testados?

Cobertura de cenários reais e não apenas o caminho feliz.

4.3 Há testes suficientes para lógica crítica?

4.4 O uso de unit e integration tests está balanceado?

• Unit tests onde fizer sentido
• Integration tests onde forem necessários

4.5 Os nomes dos testes são claros e explicativos?

5. Estilo de Código (Code Style)

O topo da pirâmide é importante, porém fácil de automatizar (e deve ser automatizado).

A ideia é não perder tempo humano com o que máquinas podem fazer.

Pontos a verificar (ou automatizar):

• Identação
• Formatação
• Imports organizados
• Regras de linting
• Convenções da equipe

A pirâmide deixa claro que nem todos os aspectos de um code review têm o mesmo peso. A ordem apresentada destaca os tópicos que possuem maior impacto no sistema — e também os mais difíceis e custosos de corrigir posteriormente. Por isso, revisar primeiro a semântica da API e a lógica da implementação garante que o projeto evolua de maneira consistente, segura e sustentável. Já os itens no topo, como estilo e formatação, devem ser automatizados sempre que possível.

Em resumo: um bom code review foca no que realmente importa e evita desperdício de esforço com o que não traz valor.