Excelência em Revisão de Código

Transforme revisões de código de um "portão" para compartilhamento de conhecimento através de feedback construtivo, análise sistemática e melhoria colaborativa.

Quando Usar Esta Habilidade

• Revisando pull requests e alterações de código
• Estabelecendo padrões de revisão de código para equipes
• Mentorando desenvolvedores juniores através de revisões
• Conduzindo revisões de arquitetura
• Criando checklists e diretrizes de revisão
• Melhorando a colaboração em equipe
• Reduzindo o tempo do ciclo de revisão de código
• Mantendo padrões de qualidade de código

Princípios Fundamentais

1. A Mentalidade de Revisão

Objetivos da Revisão de Código:

• Capturar bugs e casos extremos
• Garantir a manutenibilidade do código
• Compartilhar conhecimento entre a equipe
• Aplicar padrões de codificação
• Melhorar o design e a arquitetura
• Construir a cultura da equipe

Não são Objetivos:

• Exibir conhecimento
• Criticar formatação (use linters)
• Bloquear o progresso desnecessariamente
• Reescrever para sua preferência

2. Feedback Eficaz

Bom Feedback é:

• Específico e acionável
• Educacional, não julgador
• Focado no código, não na pessoa
• Equilibrado (elogiar o bom trabalho também)
• Priorizado (crítico vs. bom ter)

❌ Bad: "This is wrong."
✅ Good: "This could cause a race condition when multiple users
access simultaneously. Consider using a mutex here."

❌ Bad: "Why didn't you use X pattern?"
✅ Good: "Have you considered the Repository pattern? It would
make this easier to test. Here's an example: [link]"

❌ Bad: "Rename this variable."
✅ Good: "[nit] Consider `userCount` instead of `uc` for
clarity. Not blocking if you prefer to keep it."

3. Escopo da Revisão

O Que Revisar:

• Correção da lógica e casos extremos
• Vulnerabilidades de segurança
• Implicações de performance
• Cobertura e qualidade dos testes
• Tratamento de erros
• Documentação e comentários
• Design e nomenclatura de APIs
• Adequação arquitetural

O Que Não Revisar Manualmente:

• Formatação de código (use Prettier, Black, etc.)
• Organização de imports
• Violações de linting
• Erros de digitação simples

Processo de Revisão

Fase 1: Coleta de Contexto (2-3 minutos)

Before diving into code, understand:

1. Read PR description and linked issue
2. Check PR size (>400 lines? Ask to split)
3. Review CI/CD status (tests passing?)
4. Understand the business requirement
5. Note any relevant architectural decisions

Fase 2: Revisão de Alto Nível (5-10 minutos)

1. **Architecture & Design**
   - Does the solution fit the problem?
   - Are there simpler approaches?
   - Is it consistent with existing patterns?
   - Will it scale?

2. **File Organization**
   - Are new files in the right places?
   - Is code grouped logically?
   - Are there duplicate files?

3. **Testing Strategy**
   - Are there tests?
   - Do tests cover edge cases?
   - Are tests readable?

Fase 3: Revisão Linha por Linha (10-20 minutos)

For each file:

1. **Logic & Correctness**
   - Edge cases handled?
   - Off-by-one errors?
   - Null/undefined checks?
   - Race conditions?

2. **Security**
   - Input validation?
   - SQL injection risks?
   - XSS vulnerabilities?
   - Sensitive data exposure?

3. **Performance**
   - N+1 queries?
   - Unnecessary loops?
   - Memory leaks?
   - Blocking operations?

4. **Maintainability**
   - Clear variable names?
   - Functions doing one thing?
   - Complex code commented?
   - Magic numbers extracted?

Fase 4: Resumo e Decisão (2-3 minutos)

1. Summarize key concerns
2. Highlight what you liked
3. Make clear decision:
   - ✅ Approve
   - 💬 Comment (minor suggestions)
   - 🔄 Request Changes (must address)
4. Offer to pair if complex

Antes de escrever o feedback da revisão, leia references/review-techniques.md para checklists, enquadramento de perguntas, colaboração e técnicas de severidade.

Antes de revisões específicas de linguagem, arquitetura, qualidade de testes ou segurança, leia references/review-patterns.md para padrões de revisão e checklists.

Dando Feedback Difícil

Padrão: Método Sanduíche (Modificado)

Tradicional: Elogio + Crítica + Elogio (parece falso)

Melhor: Contexto + Problema Específico + Solução Útil

Exemplo:
"Notei que a lógica de processamento de pagamentos está inline no
controlador. Isso torna mais difícil testar e reutilizar.

[Problema Específico]
A função calculateTotal() mistura cálculo de impostos,
lógica de desconto e consultas ao banco de dados, tornando difícil
fazer testes unitários e raciocinar sobre ela.

[Solução Útil]
Poderíamos extrair isso para uma classe PaymentService? Isso
a tornaria testável e reutilizável. Posso fazer um pair programming com você

…