Cultura de Revisão de Código
A revisão de código é o principal ciclo de ensino da equipe para a arte em Python: tipos, armadilhas assíncronas, segurança SQL e lacunas de teste. Uma cultura de alto impacto significa padrões claros, feedback respeitoso e retorno previsível - não um perfeccionismo que bloqueia a entrega.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
## Modelo de descrição de PR
**Intenção:** uma frase
**Risco:** flag de migração / perf / segurança
**Evidência de teste:** caminho do pytest, captura de tela, nota de carga
**Rollback:** plano de flag ou reversão
## Níveis de comentários de revisão
🔴 Deve corrigir - correção, segurança, perda de dados
🟡 Deve corrigir - clareza, teste ausente (autor pode adiar com ticket)
🟢 Nit - estilo; a critério do autorQuando usar isto:
- A latência das revisões excede rotineiramente 24 horas
- As revisões são guerras de estilo sem ensino
- Juniores temem postar PRs
- Incidentes rastreiam para verificações de revisão perdidas
Exemplo de Trabalho
# Autor aborda a revisão com comentário explícito de trade-off
# REVISÃO: manteve ORM síncrono aqui intencionalmente - RFC-042 fase 1 somente leitura.
# Migração assíncrona rastreada em ENG-4412.
def get_catalog_item(item_id: str) -> dict[str, object]:
...## Checklist do Revisor (Python)
- [ ] Tipos em funções públicas / modelos Pydantic validados
- [ ] Sem I/O bloqueante em async def sem asyncio.to_thread
- [ ] Consultas DB parametrizadas; sem concatenação SQL de string
- [ ] Testes cobrem o caminho feliz + um modo de falha
- [ ] Logging estruturado; sem PII em mensagensO que isso demonstra:
- Intenção e risco do PR visíveis antes da leitura do diff
- Níveis de comentários separam bloqueadores de nits
- Trabalho adiado vincula ao ticket, não a loops de revisão intermináveis
- Checklist específico de Python captura problemas gerais da frota
Mergulho Profundo
Como Funciona
- Responsabilidade do autor - Diffs pequenos, auto-revisão, testes executados localmente com
uv run pytest. - Responsabilidade do revisor - Responder dentro do SLA; fazer perguntas antes de prescrever reescritas.
- Ensino - Vincular a um documento interno ou página de SME ao sugerir um padrão.
- Rotação - Espalhar conhecimento de domínio; evitar um único gatekeeper.
- Automação - Ruff, mypy/pyright e scanners de segurança lidam com problemas mecânicos.
Diretrizes de SLA de Revisão
| Tamanho do PR | Primeira resposta alvo |
|---|---|
| < 200 LOC | Mesmo dia útil |
| 200-500 LOC | 24 horas |
| > 500 LOC | Autor deve dividir |
Notas de Python
# pyproject.toml - deixe o CI impor o estilo para que a revisão se concentre no design
[tool.ruff]
line-length = 100
select = ["E", "F", "I", "UP", "B", "ASYNC"]Armadilhas
- LGTM sem ler testes - Regressões são enviadas. Correção: Exigir evidência de teste no modelo de PR.
- Comentários de Nit como bloqueadores - Moral e velocidade morrem. Correção: Usar o nível 🟢; agrupar nits uma vez.
- PRs gigantes - Ninguém revisa profundamente. Correção: Dividir por feature flag ou fatia vertical.
- Revisor reescreve o patch inteiro - O autor aprende pouco. Correção: Sugerir direção + link para exemplo.
- Apenas seniors revisam - O fator ônibus cresce. Correção: Emparelhar revisor júnior com sênior em grandes alterações.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Programação em par | Código novo e complexo | CRUD simples com testes |
| Sessão de revisão em grupo | Mudança de arquitetura | Pequenos PRs diários |
| Bots de aprovação automática | Erro de digitação em documentação | Lógica de aplicação |
| Inspeção formal | Segurança regulamentada | Velocidade normal do produto |
FAQs
Quantos revisores são necessários?
Um para rotina; dois para segurança, migrações ou bibliotecas compartilhadas.
Os revisores devem executar o código localmente?
Para mudanças arriscadas sim; caso contrário, confie no CI se os testes forem abrangentes.
Como lidar com revisões discordantes?
O autor responde com a justificativa; escalar para o líder técnico se houver impasse.
Revisar migrações assíncronas especialmente?
Sim - verificar bloqueio de loop, configurações de pool e flag de rollback.
Comentários sobre código gerado?
Revisar entradas e modelos do gerador, não cada linha de saída.
Como revisar notebooks?
Focar em vazamento de dados, não determinismo e caminho de promoção para produção.
Limites de tamanho de PR?
Limite suave de 400 LOC alterados; exceções precisam de link RFC.
Revisar o próprio código?
Nunca ser o único aprovador; o autor pode mesclar após outra aprovação apenas.
Como medir a saúde da revisão?
Tempo para a primeira revisão, proporção de níveis de comentários, taxa de defeitos pós-merge.
Revisão assistida por LLM?
Usar para passar no checklist; o humano é responsável pela segurança e correção de domínio.
Relacionados
- Mentoria e Nivelamento - revisões como ensino
- Executando Revisões de Design - antes de grandes PRs
- Lidando com Desacordos Técnicos - impasses
- Linting e Formatação - automatizar nits
- Testes pytest - expectativas de teste
Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.