Cognitive Complexity: por que duas funções com a mesma Ciclomática podem ter custos completamente diferentes

Você já abriu um arquivo, viu uma função com complexidade ciclomática baixa e, mesmo assim, levou 40 minutos para entender o que ela fazia? Aconteceu porque a Ciclomática conta caminhos — mas não diz nada sobre o quanto seu cérebro precisa segurar enquanto navega por eles.

A Ciclomática conta caminhos. A Cognitive Complexity mede o que o seu cérebro paga para segui-los — e a diferença explica por que uma função com complexidade ciclomática 4 pode ser trivial e outra, com a mesmíssima 4, pode roubar 40 minutos da sua tarde.

O que este artigo explora:

• O paradoxo de duas funções com a mesma Ciclomática e custos cognitivos completamente diferentes
• Como a Cognitive Complexity é calculada — passo a passo, com exemplo de código
• Por que o aninhamento é punido cumulativamente (e o que isso tem a ver com memória de trabalho)
• A propriedade de "familiaridade" no código de time — e o que ela destrava
• Por que LLMs também sofrem com Cognitive Complexity alta
• Como reduzir Cognitive via extração com nomeação semântica
• Plano operacional em 4 passos para começar hoje
• Ferramentas que medem Cognitive Complexity out-of-the-box
• Cinco pontos-chave para levar embora

O paradoxo

Considere os dois exemplos abaixo. Os dois têm exatamente a mesma Ciclomática (4). Mas qualquer dev sabe imediatamente qual dos dois é doloroso de ler:

// Ciclomática 4 — fácil de ler
function classify(order) {
  if (order.value > 1000) return 'PREMIUM';
  if (order.value > 100)  return 'STANDARD';
  if (order.items > 10)   return 'BULK';
  return 'BASIC';
}

// Ciclomática 4 — sofrimento
function classify(order) {
  if (order.user) {
    if (order.user.active) {
      if (order.value > 1000) {
        if (order.items > 10) {
          return 'PREMIUM_BULK';
        }
      }
    }
  }
  return 'BASIC';
}

Mesmo número de caminhos. Custos cognitivos completamente diferentes. A Cognitive Complexity é a métrica que captura essa diferença.

Como a Cognitive Complexity é calculada

A SonarSource introduziu a métrica em 2018 para preencher uma lacuna que se tornou evidente após décadas de uso da métrica Ciclomática. A regra é simples no princípio: o aninhamento é punido de forma cumulativa.

• Cada estrutura de controle (if, for, while, catch, etc.) → +1 base
• Mais +1 por nível de aninhamento em que ela está
• Operadores lógicos em sequência (&&, ||) somam +1 cada após o primeiro
• else e else if somam +1 (são bifurcações adicionais)

Resultado: um if no nível raiz custa 1. O mesmo if aninhado no nível 4 custa 4. O peso explode com a profundidade — porque o leitor precisa reter o contexto de todos os níveis acima para entender por que aquela condição está ali.

// Cognitive Complexity = 10 (não 4)
function classify(order) {
  if (order.user) {                    // +1 (nível 1)
    if (order.user.active) {           // +2 (nível 2)
      if (order.value > 1000) {        // +3 (nível 3)
        if (order.items > 10) {        // +4 (nível 4)
          return 'PREMIUM_BULK';
        }
      }
    }
  }
  return 'BASIC';
}

Dez. Para uma função que faz, conceitualmente, uma classificação simples.

Por que o aninhamento é punido tanto

A justificativa é cognitiva, não estética. Para entender uma instrução no quarto nível de aninhamento, o desenvolvedor precisa manter ativo na memória de trabalho:

1. A condição do nível 1 (que precisa ser verdadeira pra chegar aqui)
2. A condição do nível 2 (idem)
3. A condição do nível 3 (idem)
4. A instrução em si (no nível 4)

Pesquisa sobre memória de curto prazo aponta que humanos conseguem reter confortavelmente entre 4 e 7 itens simultaneamente. O aninhamento profundo preenche esse buffer rapidamente. Por isso, a métrica é cumulativa: reflete o custo real de processar o código, não a estrutura formal.

Código que parece escrito por uma única pessoa

O objetivo de monitorar Cognitive Complexity não é zerar o número. É manter um teto que garanta familiaridade — a propriedade pela qual qualquer dev do time pode abrir qualquer arquivo do sistema e entender o fluxo sem precisar de um tour guiado.

Quando o time tem essa propriedade, várias coisas mudam:

• O dev novo se onboarda mais rápido. Não precisa decifrar o estilo individual de cada autor.
• O dev veterano não tem medo de mexer em áreas desconhecidas. O padrão é previsível.
• Code review é sobre conteúdo, não sobre estilo. As discussões tornam-se mais técnicas, menos estéticas.
• A IA generativa funciona melhor. LLMs geram código mais útil quando o contexto é navegável.

“

Não é só quebrar a função — é quebrar e dar nomes que removam a necessidade de processar o "como" no nível mais alto.

Como reduzir Cognitive Complexity

A técnica é extração com nomeação semântica. Não é só quebrar a função — é quebrar e dar nomes que removam a necessidade de processar o "como" no nível mais alto.

function classify(order) {
  if (order.user) {
    if (order.user.active) {
      if (order.value > 1000) {
        if (order.items > 10) {
          return 'PREMIUM_BULK';
        }
      }
    }
  }
  return 'BASIC';
}

function classify(order) {
  if (!isEligibleForPremium(order)) return 'BASIC';
  if (isBulkOrder(order))           return 'PREMIUM_BULK';
  return 'PREMIUM';
}

function isEligibleForPremium(order) {
  return order.user?.active && order.value > 1000;
}

function isBulkOrder(order) {
  return order.items > 10;
}

A função original ainda existe, distribuída em três funções. O leitor do classify agora entende a lógica em segundos — sem precisar processar o como de cada predicado.

O impacto da Cognitive Complexity no uso de IA

A IA generativa também tem um buffer de memória de trabalho limitado — só que, diferente do humano, ela não percebe quando o ultrapassa. Quando você pede ao Copilot ou Claude Code para "modificar esta função" e ela tem Cognitive 30, o modelo provavelmente vai gerar código que ignora algum nível de aninhamento, ou produzir alucinação (código que parece correto mas não funciona). Cognitive alta é a região em que os outputs do LLM mais frequentemente se quebram silenciosamente.

O que acontece em código com Cognitive alta + IA

• A IA mantém ou piora o padrão. Em código com aninhamento profundo, ela tende a continuar aninhando — em vez de extrair predicados nomeados que reduziriam Cognitive.
• Aumento de duplicação. Sem uma modularização clara, a IA não reconhece que uma lógica equivalente já existe em outro lugar. Gera nova versão. Cada prompt pode gerar uma nova cópia.
• Maior chance de bugs introduzidos. O LLM perde contexto entre níveis de aninhamento — pelo mesmo motivo pelo qual os humanos também perdem. A diferença é que o humano, pelo menos, suspeita; o modelo entrega com confiança.
• Testes automatizados também ficam complexos. A IA gera testes que herdam a estrutura aninhada da função. Resultado: testes longos, frágeis, com setup denso — difíceis de manter quando o código muda.

Ferramentas que medem Cognitive Complexity

A métrica foi originalmente proposta por G. Campbell em 2018 e popularizada por linters como SonarQube/SonarLint (multi-language), cognitive-complexity-ts (TypeScript), Detekt (Kotlin), e a categoria como um todo em ferramentas modernas de análise estática. A plataforma SQA da Codurance integra essa medição com as outras quatro métricas da série em um diagnóstico unificado — útil quando você quer ver Cognitive em conjunto com Cyclomatic, Smells, Bugs e Duplication.

Como a Codurance pode ajudar?

A Codurance acompanha times de engenharia que querem instrumentar a saúde do código sem virar gestores. Ajudamos Tech Leads e Staff Engineers a integrar Cognitive Complexity em pipelines de CI/CD, definir thresholds operacionais sustentáveis e estabelecer rituais de refatoração que mantêm a propriedade de "familiaridade" no código ao longo do tempo.

Se você quer aplicar essas práticas no seu time, entre em contato hoje.

Duas funções podem ter a mesma complexidade ciclomática…
e ainda assim uma ser muito mais difícil de entender.

O problema?
Estamos medindo caminhos — não esforço humano.

Ciclomática conta decisões.
Mas cada decisão não custa o mesmo para quem lê.

Alguns fluxos são simples.
Outros… exigem muito mais do cérebro.

Mais caminhos = mais testes.
Mas também:

→ mais carga cognitiva
→ mais chance de erro
→ mais dificuldade de manutenção

Nem toda complexidade é igual.

Código bom não é só o que funciona.
É o que alguém consegue entender rápido.

Reduzir complexidade cognitiva significa:

→ menos bugs
→ mais velocidade
→ decisões melhores

5 An optional caption for the image that will be added to the gallery. Enter any descriptive text for this image that you would like visitors to be able to read.