Complexidade Ciclomática: O Que É e Como Calcular

A complexidade ciclomática é uma métrica de software, criada por Thomas J. McCabe em 1976, que conta o número de caminhos de execução independentes de um programa. Ela é usada para avaliar testabilidade e manutenção do código: quanto mais condicionais e loops, maior o valor — e maior o risco de defeitos.

• O que é complexidade ciclomática?
• Como calcular a complexidade ciclomática?
• Qual é um bom valor de complexidade ciclomática?
• Benefícios da medição para manutenção e testes
• Quais ferramentas calculam a complexidade ciclomática?
• Como reduzir a complexidade ciclomática na prática

O que é complexidade ciclomática?

Complexidade ciclomática é uma métrica quantitativa que representa o número de caminhos linearmente independentes que a execução de um programa pode percorrer. Ela foi proposta por Thomas J. McCabe no artigo "A Complexity Measure" (IEEE Transactions on Software Engineering, 1976) como uma forma objetiva e mensurável de avaliar a complexidade estrutural do software.

O raciocínio é direto: cada estrutura de controle — if, else, while, for, case — cria um desvio possível no fluxo do programa. Quanto mais desvios, mais caminhos distintos existem, mais cenários precisam ser testados e mais difícil fica entender o que o código realmente faz. Se você ainda está consolidando esses fundamentos, o guia de lógica de programação e estruturas de controle do CodeCrush cobre a base necessária.

A complexidade ciclomática também define um piso para a cobertura de testes: uma função com complexidade 7 exige pelo menos 7 casos de teste para exercitar todos os seus caminhos independentes — princípio central da técnica de basis path testing, usada em testes de caixa branca.

Como calcular a complexidade ciclomática?

A complexidade ciclomática é calculada sobre o grafo de fluxo de controle do programa pela fórmula de McCabe: M = E − N + 2P, onde E é o número de arestas do grafo, N é o número de nós e P é o número de componentes conexos (normalmente 1 para uma função isolada).

No dia a dia, ninguém desenha o grafo à mão. Existe um atalho equivalente:

1. Comece com o valor 1 para a função.
2. Some 1 para cada if, else if, while, for e do-while.
3. Some 1 para cada case de um switch.
4. Some 1 para cada operador condicional ternário e para cada operador lógico de curto-circuito (&&, ||) em condições.
5. O total é a complexidade ciclomática da função.

Um exemplo rápido: uma função com um if/else e um loop for tem complexidade 3 (1 base + 1 do if + 1 do for). Uma função sem nenhum desvio — só instruções sequenciais — tem complexidade 1, o mínimo possível.

Qual é um bom valor de complexidade ciclomática?

O limite clássico é 10 por função, proposto pelo próprio McCabe em 1976 e reafirmado pelo NIST (National Institute of Standards and Technology) na publicação SP 500-235, "Structured Testing" (Watson & McCabe, 1996), que aceita limites de até 15 em equipes com processos maduros e testes rigorosos. Ferramentas modernas adotam padrões diferentes, como mostra a tabela:

A documentação da Microsoft resume bem o consenso: "A low cyclomatic complexity generally indicates a method that is easy to understand, test, and maintain" — uma complexidade ciclomática baixa geralmente indica um método fácil de entender, testar e manter. Vale lembrar que o limite é um alerta, não uma lei: um switch grande e legível pode ultrapassá-lo sem representar risco real.

Benefícios da medição para manutenção e testes

Medir a complexidade ciclomática traz benefícios concretos em quatro frentes do ciclo de desenvolvimento:

• Identificação de pontos de risco: funções com complexidade alta concentram estatisticamente mais defeitos; a métrica aponta onde a depuração e a revisão de código devem focar primeiro.
• Priorização de testes: o valor da métrica indica o número mínimo de casos de teste para cobrir todos os caminhos, orientando a estratégia de testes de software para as áreas críticas.
• Manutenção mais barata: código de baixa complexidade é mais fácil de entender, estender e revisar, reduzindo o custo de cada mudança ao longo da vida do sistema.
• Guia objetivo de refatoração: em vez de discutir estilo, a equipe usa um número para decidir o que simplificar — um pilar de práticas de clean code.

A complexidade ciclomática funciona melhor como termômetro contínuo do que como auditoria pontual: acompanhar a tendência do valor a cada entrega revela se a base de código está ficando mais saudável ou acumulando dívida técnica.

Quais ferramentas calculam a complexidade ciclomática?

Ferramentas de análise estática calculam a complexidade ciclomática automaticamente a partir do código-fonte, sem que o desenvolvedor precise montar grafos ou contar decisões manualmente. As opções mais usadas são:

• SonarQube: plataforma de análise contínua multi-linguagem que reporta complexidade por função, arquivo e projeto.
• ESLint: a regra complexity alerta quando uma função JavaScript ou TypeScript ultrapassa o limite configurado (padrão 20).
• PMD: analisador de código aberto com regras de complexidade para Java, Apex e outras linguagens.
• Radon: biblioteca Python que classifica funções em graus de A a F conforme a complexidade.
• Analisadores do .NET: a regra CA1502 mede a métrica em C# e Visual Basic com limiar configurável.

O maior ganho vem da integração dessas ferramentas ao fluxo de trabalho: rodando na IDE, elas dão feedback em tempo real enquanto o código é escrito; rodando no pipeline de CI/CD, bloqueiam a entrada de funções acima do limite antes que cheguem à produção.

Como reduzir a complexidade ciclomática na prática

Reduzir a complexidade ciclomática significa eliminar ou isolar pontos de decisão, e algumas técnicas de refatoração resolvem a maioria dos casos:

1. Extraia funções: divida uma função grande em funções menores e nomeadas; cada uma carrega parte das decisões e fica testável isoladamente.
2. Use retornos antecipados: substitua condicionais aninhadas por cláusulas de guarda (return no início), achatando a estrutura do código.
3. Troque condicionais por polimorfismo ou mapas: cadeias de if/else sobre um tipo ou categoria podem virar despacho por objeto, dicionário ou padrão Strategy.
4. Simplifique expressões booleanas: extraia condições compostas para variáveis ou funções com nomes descritivos, reduzindo operadores lógicos encadeados.
5. Meça antes e depois: rode a ferramenta de análise após cada refatoração para confirmar que o valor caiu sem alterar o comportamento — de preferência com uma suíte de testes cobrindo os caminhos existentes.

Conclusão

A complexidade ciclomática continua sendo, cinquenta anos depois de McCabe, uma das métricas com melhor custo-benefício da engenharia de software: um único número, calculado de graça por ferramentas que você provavelmente já usa, aponta exatamente onde o código vai doer primeiro. A recomendação prática é pragmática — configure o limite de 10 do NIST como alerta no seu linter e no CI, trate violações como convite à refatoração e reserve as exceções para casos genuinamente legíveis, como um switch extenso. Quem mede a complexidade a cada entrega raramente é surpreendido por ela.