Checklist de Revisão de Código

Uma revisão responde a uma única pergunta: "Este código se tornará um problema para outra pessoa em três meses?" Percorra os cinco eixos em ordem; cada eixo recebe aprovação / reprovação / N/A, e cada reprovação deve vir com uma correção concreta.

Quando Usar

• Use quando o usuário pedir para revisar código, um diff ou um pull request.
• Use quando uma revisão deve permanecer acionável e pular pequenas discussões de estilo.

Fluxo de Trabalho

1. Verifique o escopo primeiro: olhe o tamanho do diff. Acima de ~400 linhas alteradas, peça uma divisão antes de revisar — a qualidade da revisão em diffs enormes sempre colapsa.
2. Verifique eixo por eixo (ordem = prioridade):
   • Correção: casos extremos (nulo, vazio, zero, negativo, superdimensionado), suposições de concorrência/tempo, tratamento de erros (exceções são engolidas?). O único eixo que pode bloquear um merge.
   • Segurança: entrada do usuário está sendo concatenada em comandos SQL / shell / HTML; segredos ou tokens estão codificados; o log vaza dados sensíveis.
   • Legibilidade: nomes dizem o que as coisas são; cada função faz uma coisa; números mágicos são nomeados. Marque apenas o que você não consegue entender — não "eu escreveria de forma diferente".
   • Desempenho: consultas repetidas ou recálculo dentro de loops; problemas N+1; cópias evitáveis de objetos grandes. Nenhuma especulação de desempenho sem dados ("isso pode ficar lento" não é um comentário).
   • Cobertura de testes: a nova lógica tem testes; casos extremos têm casos. Testes totalmente verdes com o caminho crítico descoberto ainda são enviados de volta.
3. Escreva os comentários: formato fixo — [axis] file:line problem → suggested fix. Apenas sugestões acionáveis; "poderia ser otimizado" não é uma delas.
4. Triagem: Must fix (correção / segurança) vs Should fix (legibilidade / desempenho / testes). "Deve corrigir" não bloqueia o merge, mas diga isso explicitamente.

Regras

• No máximo 10 comentários por revisão. Mais do que isso significa que o código está muito quebrado — envie de volta para uma reescrita em vez de avaliar 50 itens.
• Sem policiamento de estilo: indentação, aspas, ponto e vírgula — isso é trabalho do linter, não de um humano.
• Fale com o diff: cada comentário deve citar uma linha de código concreta. Um comentário sem referência de código é inválido.

Checklist (versão executável mínima)

## Code review checklist

- [ ] Correctness: edge cases (null/0/negative/oversized) handled, exceptions not swallowed
- [ ] Correctness: concurrency/timing assumptions hold, no races
- [ ] Security: no SQL/shell/HTML injection points, no hard-coded secrets, no sensitive data in logs
- [ ] Readability: names are descriptive, functions have a single responsibility, no magic numbers
- [ ] Performance: no repeated queries/computation in loops, no N+1, no evidence-free performance worries
- [ ] Tests: new logic is covered, edge cases have cases
- [ ] Scope: diff ≤ ~400 lines, otherwise split first

Exemplo de comentários de revisão:

[Must fix][Correctness] order.py:87 empty order list triggers IndexError → guard for empty before taking [0]
[Should fix][Readability] order.py:92 magic number 86400 → name it SECONDS_PER_DAY

Limitações

• Cobre cinco eixos de revisão, não todas as dimensões de qualidade. Correção específica do domínio (arredondamento financeiro, conformidade de protocolo, conformidade de acessibilidade) ainda precisa de sua própria revisão especializada.
• Os cinco eixos são heurísticas para um revisor humano. Uma aprovação limpa no checklist não prova que a alteração está correta, segura ou performática.
• A revisão de segurança aqui é um checklist de leitura, não um scanner. Análise estática, auditoria de dependências e varredura de segredos são executados como ferramentas separadas.
• A habilidade revisa diffs; não pode estabelecer que os requisitos foram atendidos, e uma lista de achados vazia significa apenas que nenhum achado foi evidenciado no escopo revisado.

Antipadrões

• ❌ LGTM de passagem: aprovar antes de ler todo o diff — a revisão é teatro.
• ❌ Polícia de estilo: 18 de 20 comentários sobre aspas e quebras de linha enquanto uma desreferência de ponteiro nulo passa despercebida.
• ❌ Comentários sem código: "esta lógica parece errada" — qual lógica? Qual linha? Não dito significa inválido.
• ❌ Especulação de desempenho: "este loop pode ser lento em escala" — um comentário de desempenho sem dados é ruído.
• ❌ Avaliando 50 itens: quando há muitos problemas para listar, o movimento certo é "reescrever e reenviar", não brincar de professor.