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.
Cognitive Complexity mede o esforço mental necessário para compreender um trecho de código. Diferentemente da Ciclomática, ela pune o aninhamento de forma cumulativa — porque o cérebro humano paga um preço exponencial para reter contexto em níveis profundos. Foi proposta pela SonarSource para preencher exatamente essa lacuna.
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.
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.
if, for, while, catch, etc.) → +1 base&&, ||) somam +1 cada após o primeiroelse 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.
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:
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.
Cognitive Complexity alta não é só barreira para humanos. Também é uma barreira para a IA. Quando você pede ao Copilot ou ao Claude para "modificar esta função" e ela tem Cognitive 30, o modelo provavelmente vai gerar código que ignora algum nível de aninhamento — porque ele também tem dificuldade em reter o contexto completo.
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:
“Não é só quebrar a função — é quebrar e dar nomes que removam a necessidade de processar o "como" no nível mais alto.
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.
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.
Cognitive baixa, modularização clara e tipagem rigorosa fazem a IA trabalhar com você. Ela identifica funções existentes e reutiliza, gera código que respeita a estrutura e produz testes que cabem na cabeça. Métricas de qualidade tornam-se pré-condição para extrair valor da IA.
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.
Cyclomatic e Cognitive medem estrutura. Mas e os padrões de design ruim que não aparecem em nenhuma dessas métricas — métodos longos, duplicação de responsabilidade, classes que invadem outras? É aí que entram os Code Smells.
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.