Seu code review provavelmente está quebrado

A maioria dos code reviews encontra entre 15 e 30 por cento dos defeitos que deveriam encontrar. Isso não é um palpite. A IBM mediu isso nos anos 1970, e estudos na AT&T, HP e Microsoft confirmaram a mesma faixa década após década.

A revisão informal é barata, assíncrona e socialmente aceitável. Também é em grande parte ineficaz em encontrar bugs. Os engenheiros leem rápido demais, pulam os caminhos de erro e evitam apontar problemas reais porque ninguém quer ser a pessoa que segura o merge.

Existe uma alternativa que relata consistentemente taxas de remoção de defeitos de 60 a 90 por cento. Foi inventada na IBM em 1976 por Michael Fagan. Não requer ferramentas, IA ou orçamento. Requer algo que a maioria das equipes de engenharia se recusa a dar: estrutura.

O que é uma Fagan inspection?

Uma Fagan inspection é um processo de revisão formalmente definido, de múltiplas etapas, com funções específicas, limites de tempo, critérios de entrada e checklists. Diferente de um típico pull request review, não é uma conversa entre autor e revisor. É uma reunião estruturada com um moderador, um reader, inspectores e o autor.

O autor permanece principalmente em silêncio. A reunião é estritamente timeboxed. E o único objetivo é encontrar defeitos.

O processo segue seis etapas:

  1. Planning. O moderador seleciona o material, verifica os critérios de entrada, atribui funções e agenda a reunião. Os critérios de entrada existem por um motivo. Não se inspeciona um rascunho. O documento deve estar completo, compilável e testado antes de merecer consumir o tempo de quatro pessoas.

  2. Overview. Opcional. O autor explica o contexto se os inspectores não estiverem familiarizados com o domínio.

  3. Preparation. Cada inspector revisa o material sozinho antes da reunião. Isso é inegociável. Não se chega despreparado. Os inspectores usam checklists adaptadas aos tipos comuns de defeitos e anotam issues privadamente.

  4. Inspection. A reunião em si. O reader, que não escreveu o código, percorre-o linha por linha e parafrasia em voz alta. Os inspectores levantam issues quando detectam discrepâncias. O autor escuta. Ninguém propõe correções. O moderador impõe os limites de tempo e mantém a reunião focada apenas na identificação de defeitos.

  5. Rework. O autor corrige os defeitos.

  6. Follow-up. O moderador verifica se cada defeito foi tratado. Se muitos defeitos foram encontrados, ocorre uma reinspection.

Quatro funções mantêm o processo honesto. O moderador planeja e controla. O autor criou o trabalho e responde perguntas apenas quando solicitado. O reader parafrasia o código durante a reunião, forçando uma compreensão mais lenta e cuidadosa. Os inspectores, geralmente de dois a quatro, encontram os defeitos.

Por que a revisão informal falha onde as Fagan inspections têm sucesso

A diferença não é talento. É design de processo.

Em um típico pull request review, o revisor lê o diff no navegador, passa os olhos pelo happy path, deixa alguns comentários e aprova. Não há tempo de preparação. Não há checklist. Não há mecanismo que force o revisor a examinar o tratamento de erros ou as condições de limite. A dinâmica social recompensa velocidade e polidez, não minuciosidade.

As Fagan inspections invertem esses incentivos.

A preparação individual significa que cada inspector realmente leu o código antes da reunião começar. A paráfrase do reader força o grupo a processar o código na velocidade da compreensão em vez da velocidade da leitura rápida. As checklists direcionam a atenção para categorias conhecidas de defeitos em vez do que chama a atenção. A pressão do tempo impede que a reunião se desvie para debates de design. E separar a descoberta de defeitos da correção evita que o grupo se fixe na primeira solução sugerida.

O resultado é que as Fagan inspections pegam a maioria dos defeitos antes que cheguem ao testing ou à produção.

O custo é concentrado no início em person-hours.

O verdadeiro trade-off: Person-hours vs. escape de defeitos

Aqui está o motivo pelo qual a maioria das equipes não usa Fagan inspections.

Uma única inspection requer de quatro a seis pessoas em uma sala por até duas horas para revisar aproximadamente 250 linhas de código. Isso são de 8 a 12 person-hours para uma pequena alteração. Em um workflow moderno de CI/CD onde as equipes fazem deploy várias vezes ao dia, isso parece absurdo.

O processo também parece burocrático. Critérios de entrada, funções formais, checklists impressas, verificação de follow-up. A maioria dos engenheiros vai odiar por princípio. E não escala para diffs grandes. Uma refatoração de duas mil linhas exigiria oito reuniões de inspection separadas.

Mas o cálculo muda quando se olha para o custo total em vez do custo da reunião.

Os dados originais da IBM mostraram que encontrar e corrigir um defeito durante a inspection custava cerca de um décimo do que custava encontrar e corrigir o mesmo defeito durante o testing. Quando escapava para a produção, a proporção crescia para vinte ou trinta para um.

Então sim, a inspection é cara. Ainda assim é mais barata do que debugar incidents de produção, queimar capacidade de sprint em correções reativas e perder a confiança do cliente.

O problema é que as economias são invisíveis. Você não pode medir o bug que evitou. O custo da reunião é imediato e óbvio. É por isso que a revisão informal vence na maioria das organizações. Ela otimiza a velocidade visível em vez da qualidade invisível.

Executando uma Fagan inspection simplificada em 2026

Você não precisa adotar toda a cerimônia. A maioria das equipes pode obter setenta por cento do benefício com vinte por cento do overhead mantendo as mecânicas principais e eliminando a papelada.

Aqui está uma sequência prática:

Exija preparação individual antes de qualquer revisão síncrona. Se você não leu o código, não participa.

Atribua um reader que não escreveu o código para percorrer a lógica em voz alta. Não deixe o autor conduzir. Parafrasear força o grupo a processar cada branch.

Use uma checklist adaptada aos tipos de defeitos mais comuns da sua equipe. Comece com a lista abaixo e adicione itens à medida que aprende com defeitos escapados.

Timebox de noventa minutos. Termine na hora, mesmo que não tenha acabado. Agende uma segunda sessão em vez de deixar a fadiga destruir a qualidade.

Mantenha o autor passivo. Eles respondem apenas a perguntas de esclarecimento. Sem defender escolhas de design.

Registre defeitos, não soluções. Corrija os defeitos após a reunião.

Para tornar isso concreto, aqui está um pequeno script Python que planeja uma inspection, estima o tempo e imprime checklists específicas por função:

#!/usr/bin/env python3
"""
Plan a Fagan-style inspection: estimate time and emit checklists.
"""

import argparse


def count_lines(filepath):
    """Count non-blank lines."""
    try:
        with open(filepath, "r") as f:
            return sum(1 for line in f if line.strip())
    except Exception:
        return 0


def plan_inspection(files, rate=125):
    """
    rate: reviewable lines per hour. Fagan recommended 100-125 for code.
    """
    total = sum(count_lines(f) for f in files)
    hours = total / rate
    minutes = hours * 60

    print(f"Total reviewable lines: {total}")
    print(f"At {rate} lines/hour, schedule: {hours:.1f} hours ({minutes:.0f} min)")

    if hours > 2:
        sessions = int(hours / 2) + 1
        print(f"WARNING: exceeds 2-hour limit. Split into {sessions} sessions.")

    print("\n--- ROLE: Reader ---")
    print("Paraphrase each block aloud. Do not just read variable names.")
    print("Pause at every conditional, loop boundary, and API call.")

    print("\n--- ROLE: Inspector ---")
    checklist = [
        "Off-by-one in loops and array or slice access",
        "Null, None, or undefined dereferences",
        "Resource leaks: files, connections, locks, contexts",
        "Error paths: are they handled, returned, and tested?",
        "Return values: are they checked before use?",
        "Shared mutable state and thread safety",
        "Boundary conditions and input validation",
        "Invariant violations: what should stay true, and does it?",
    ]
    for item in checklist:
        print(f"  [ ] {item}")

    print("\n--- ROLE: Moderator ---")
    print("Start on time. End on time.")
    print("No design debates. No solution proposals.")
    print("Record each defect with: file, line, severity, type.")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Plan a Fagan inspection")
    parser.add_argument("files", nargs="+", help="Source files to inspect")
    parser.add_argument("--rate", type=int, default=125, help="Lines per hour")
    args = parser.parse_args()

    plan_inspection(args.files, args.rate)

Salve como inspect.py, execute python inspect.py src/auth.py src/orders.py, e você terá uma estimativa de tempo e uma checklist.

Perguntas frequentes

O que é uma Fagan inspection?

Uma Fagan inspection é um processo de revisão estruturado de seis etapas com funções definidas, critérios de entrada e checklists. Foi desenvolvido por Michael Fagan na IBM em 1976 para encontrar defeitos em produtos de trabalho de software antes do testing.

Qual a diferença entre uma Fagan inspection e um pull request review?

Um pull request review é tipicamente assíncrono, informal e conduzido pelo autor. Uma Fagan inspection é uma reunião síncrona com funções atribuídas, preparação individual obrigatória, limites de tempo rigorosos e uma regra de que o autor permanece em silêncio enquanto outros encontram defeitos.

Por que as Fagan inspections não são mais comuns?

São caras em person-hours, parecem burocráticas para equipes modernas e não escalam bem para mudanças grandes e frequentes. O custo é visível e imediato. Os defeitos evitados são invisíveis.

As Fagan inspections podem funcionar em um ambiente ágil ou CI/CD?

Sim, mas com modificações. A maioria das equipes usa versões simplificadas: preparação individual obrigatória, um reader que parafrasia, uma checklist e um timebox rigoroso. O processo formal completo geralmente é reservado para modules críticos ou de alto risco.

Experimente em um module

Você não precisa reescrever seu processo. Escolha um module que teve defeitos escapados no último mês. Reúna três engenheiros que não o escreveram. Dê a eles o código e uma checklist com vinte e quatro horas de antecedência. Agende noventa minutos. Atribua um reader. Faça o autor ouvir.

Meça o que encontrar. Depois decida se a reunião custou mais do que os bugs teriam custado.

Se você quiser os dados originais, o artigo de 1976 de Fagan “Design and Code Inspections to Reduce Errors in Program Development” ainda é a melhor referência. Tem cinquenta anos, e a maioria das equipes ainda não alcançou esse nível.