Regra
Evite níveis de aninhamento profundos.
Aninhamento profundo torna o código difícil de ler e entender.
Linguagens suportadas: 45+

Introdução

Código com quatro, cinco ou seis níveis de aninhamento cria uma carga cognitiva que retarda o desenvolvimento. Cada nível de aninhamento dificulta o rastreamento de condições ativas, caminhos de erro e lógica de negócio. Aninhamento excessivo frequentemente indica abstrações ausentes ou oportunidades para usar retornos antecipados e cláusulas de guarda.

Por que isso importa

Manutenibilidade do código e riscos de bugs: Aninhamento profundo cria o "código de seta" que empurra a lógica para fora da tela, atrasando a revisão de código. Desenvolvedores perdem casos de borda ao modificar código aninhado porque não conseguem ver todas as condições que devem ser satisfeitas. Alterações que parecem corretas isoladamente podem quebrar suposições feitas em níveis superiores.

Complexidade de teste e depuração: Cada nível de aninhamento dobra os casos de teste necessários para cobertura, criando uma explosão exponencial de caminhos. Stack traces de erros não mostram quais condições levaram a eles, tornando os bugs difíceis de reproduzir.

Exemplos de código

❌ Não-conforme:

function processOrder(order) {
    if (order) {
        if (order.items && order.items.length > 0) {
            if (order.customer) {
                if (order.customer.address) {
                    if (order.paymentMethod) {
                        if (validatePayment(order.paymentMethod)) {
                            return submitOrder(order);
                        }
                    }
                }
            }
        }
    }
    return { error: 'Invalid order' };
}

Por que está errado: Seis níveis de aninhamento dificultam a visualização da lógica de negócio real (envio de pedido) enterrada no fundo. Cada verificação de condição adiciona outra camada de indentação, e o tratamento de erros não é claro porque não há indicação de qual validação específica falhou.

✅ Compatível:

function processOrder(order) {
    if (!order) {
        return { error: 'Order is required' };
    }

    if (!order.items || order.items.length === 0) {
        return { error: 'Order must contain items' };
    }

    if (!order.customer?.address) {
        return { error: 'Customer address is required' };
    }

    if (!order.paymentMethod || !validatePayment(order.paymentMethod)) {
        return { error: 'Invalid payment method' };
    }

    return submitOrder(order);
}

Por que isso importa: Cláusulas de guarda com retornos antecipados nivelam o aninhamento para um único nível. Cada validação é explícita e retorna uma mensagem de erro específica. O 'caminho feliz' (envio do pedido) é visível no final sem qualquer aninhamento. O código é autodocumentado e fácil de modificar sem quebrar as condições existentes.

Conclusão

Mantenha os níveis de aninhamento em três ou menos, sempre que possível. Use retornos antecipados (early returns), cláusulas de guarda (guard clauses) e funções auxiliares para achatar estruturas profundamente aninhadas. Quando você encontrar aninhamento além de três níveis, é um sinal para refatorar, extraindo métodos, invertendo condições ou repensando a abordagem. Código plano é mais fácil de ler, testar, depurar e manter do que alternativas profundamente aninhadas.