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 autor

Quando 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 mensagens

O 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

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

FAQs

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+.