Metriche di complessità dei task nello sviluppo software: guida 2026

Yury Pukhov CEO & Mobile Engineering Lead, YuSMP Group

Le metriche di complessità dei task nello sviluppo software rispondono a una domanda che ogni team di delivery si pone più volte a settimana: quanto è davvero difficile questo lavoro? Un ticket che sembra richiedere due giorni può nascondere una funzione con quaranta ramificazioni, tre integrazioni esterne e nessun test. Senza una misura condivisa della complessità, le stime slittano, i difetti si concentrano negli stessi moduli e nessuno sa spiegare perché l’ultima funzionalità “piccola” abbia richiesto un mese.

Per founder e CTO che acquistano o gestiscono capacità di sviluppo, la complessità è anche un segnale di costo. Il codice molto complesso è più lento da modificare, più difficile da testare e si rompe più spesso, aumentando in silenzio il prezzo di ogni funzionalità futura. I team che offrono servizi di product engineering con quality gate integrati trattano la complessità come una proprietà misurata del codice e del backlog, non come un’opinione espressa nello sprint planning.

Questa guida copre entrambi i lati del problema. Spiega le metriche del codice prodotte dagli strumenti di analisi statica, le misure dei task usate per dimensionare il lavoro, come condurre passo dopo passo un’analisi della complessità dei task, quali soglie sono ragionevoli, quali strumenti usare e come gli assistenti di codice IA cambiano il quadro nel 2026. Si basa sulle ricerche pubblicate da McCabe, Halstead, SonarSource e IFPUG e sulla nostra esperienza con team di delivery per clienti negli Stati Uniti e nell’UE.

Cosa sono le metriche di complessità dei task nello sviluppo software?

Le metriche di complessità dei task nello sviluppo software sono misure quantitative di quanto un’unità di lavoro sia difficile da comprendere, implementare, testare e mantenere. Vanno dalle metriche del codice, calcolate automaticamente dal codice sorgente, alle misure dei task che il team assegna in fase di pianificazione e stima.

Complessità non significa dimensione. Un file di configurazione di 300 righe può essere banale, mentre una funzione di pricing di 40 righe con condizioni annidate, fusi orari e regole valutarie può essere il codice più rischioso del sistema. Le buone metriche di complessità catturano il numero di decisioni, percorsi, dipendenze e incognite, non solo il volume di codice.

Complessità del codice e complessità del task

La complessità del codice descrive il codice sorgente esistente o risultante, mentre la complessità del task descrive il lavoro necessario per modificarlo. Le due sono collegate ma rispondono a domande diverse.

• Le metriche del codice come complessità ciclomatica, complessità cognitiva, misure di Halstead, indice di manutenibilità e accoppiamento vengono calcolate dagli strumenti direttamente dal codice. Sono oggettive e ripetibili, ma vedono solo ciò che è già scritto.
• Le misure del task come story point, function point e checklist dei fattori di complessità vengono assegnate prima dell’inizio del lavoro. Includono ciò che le metriche del codice non vedono: requisiti poco chiari, dipendenze da terzi, tecnologie nuove e vincoli normativi.

Un’analisi utile della complessità dei task combina entrambe: le metriche del codice dicono quanto è rischiosa l’area che state per toccare, le misure del task dicono quanta incertezza porta con sé la modifica.

Perché misurare la complessità dei task?

Conviene misurare la complessità dei task perché è uno dei migliori predittori di sforzo, difetti e costi di manutenzione, e perché rende visibile il rischio nascosto prima che arrivi in produzione. Una complessità misurata trasforma “sembra difficile” in un fatto di cui tutto il team può discutere.

• Stime più oneste: sapere che un ticket tocca un modulo ad alta complessità ciclomatica e modificato spesso spiega perché richiede più tempo e più test.
• Test mirati: la complessità ciclomatica indica il numero minimo di casi di test necessari per coprire ogni percorso indipendente di una funzione.
• Prevenzione dei difetti: i difetti si concentrano nei file complessi e modificati spesso, quindi i dati di complessità mostrano dove code review e test contano di più.
• Priorità di refactoring: la complessità combinata con la frequenza delle modifiche individua gli hotspot dove la pulizia ripaga più in fretta.
• Onboarding più rapido: un codice più semplice e ben strutturato permette ai nuovi sviluppatori di contribuire in sicurezza in pochi giorni invece che in settimane.
• Controllo dei fornitori: i trend di complessità nella CI offrono anche agli stakeholder non tecnici una visione oggettiva di come evolve una codebase interna o esternalizzata, se diventa più sana o più fragile.

Quali metriche di complessità del codice contano di più?

Le metriche di complessità del codice più importanti nel 2026 sono la complessità ciclomatica, la complessità cognitiva, il volume di Halstead, l’indice di manutenibilità, l’accoppiamento e la profondità di ereditarietà, oltre al code churn combinato negli hotspot. Insieme descrivono quanti percorsi ha una funzione, quanto è difficile da leggere, quanto dipende da altro codice e quanto spesso cambia.

Complessità ciclomatica

La complessità ciclomatica conta il numero di percorsi linearmente indipendenti in una funzione ed è ancora la metrica di complessità del codice più usata. Thomas McCabe la introdusse nel 1976; in pratica è pari al numero di punti decisionali (if, else if, case, cicli, operatori logici nelle condizioni, blocchi catch) più uno.

McCabe raccomandava un limite di 10 per modulo, e la NIST Special Publication 500-235 (1996) riprende questa indicazione, consentendo fino a 15 a team esperti con buoni test. Il valore indica anche ai tester il numero minimo di casi di test per la copertura completa dei percorsi. Il suo limite: uno switch piatto con dieci casi e dieci condizioni profondamente annidate ottengono lo stesso punteggio, anche se per una persona le seconde sono molto più difficili da leggere.

Complessità cognitiva

La complessità cognitiva misura quanto il codice è difficile da capire per una persona, ed è quindi un indicatore dello sforzo di manutenzione migliore della sola complessità ciclomatica. SonarSource ha pubblicato la metrica nel 2017 proprio per risolvere il problema dell’annidamento descritto sopra.

Le regole sono semplici: ogni interruzione del flusso lineare aggiunge un punto, ogni livello di annidamento aggiunge peso, e le strutture sintetiche facili da leggere, come uno switch piatto o una catena di operatori null-safe, aggiungono poco o nulla. SonarQube segnala per impostazione predefinita le funzioni oltre 15. I team che monitorano entrambe le metriche scoprono di solito che la complessità cognitiva corrisponde molto meglio all’intuizione degli sviluppatori su cosa sia “codice difficile”.

Misure di complessità di Halstead

Le misure di Halstead stimano il contenuto informativo e lo sforzo mentale del codice a partire dal conteggio di operatori e operandi. Maurice Halstead le definì nel 1977 e la maggior parte degli strumenti di analisi statica le calcola ancora oggi.

• Vocabolario: numero di operatori distinti più operandi distinti.
• Lunghezza: numero totale di operatori e operandi.
• Volume: lunghezza moltiplicata per il logaritmo in base 2 del vocabolario, approssimativamente la dimensione del programma in bit.
• Difficoltà e sforzo: valori derivati che stimano quanto il codice sia difficile da scrivere o comprendere.

Le metriche di Halstead sono utili soprattutto come linee di tendenza e come input dell’indice di manutenibilità. Da sole, i valori assoluti sono difficili da confrontare tra linguaggi diversi.

Indice di manutenibilità

L’indice di manutenibilità combina volume di Halstead, complessità ciclomatica e righe di codice in un unico punteggio che indica quanto è facile mantenere un modulo. La formula originale degli anni Novanta produceva valori fino a 171; Microsoft Visual Studio la riporta su una scala 0–100 e considera buono un valore da 20 in su, medio tra 10 e 19 e scarso sotto 10.

L’indice è comodo per le dashboard e per individuare i file peggiori in una grande codebase legacy. Poiché mescola più segnali, però, nasconde il motivo di un punteggio basso: analizzate sempre le metriche sottostanti prima di decidere cosa rifattorizzare.

Accoppiamento, coesione e profondità di ereditarietà

Le metriche di accoppiamento ed ereditarietà misurano la complessità strutturale tra moduli anziché all’interno di una singola funzione. Una classe che dipende da altre venti è rischiosa da modificare anche se ciascuno dei suoi metodi è semplice.

Il riferimento classico è la suite di Chidamber e Kemerer del 1994: Coupling Between Objects (CBO), Depth of Inheritance Tree (DIT), Lack of Cohesion in Methods (LCOM) e Response for a Class (RFC). Per servizi e moduli lo stesso principio vale a livello architetturale: fan-in, fan-out e cicli di dipendenze mostrano dove una modifica si propagherà nell’intero sistema.

Code churn e analisi degli hotspot

L’analisi degli hotspot combina la complessità con la frequenza delle modifiche ricavata dal controllo di versione, ed è il modo più pratico per capire dove la complessità costa davvero denaro. Il codice complesso che nessuno tocca ha bassa priorità; il codice complesso che cambia a ogni sprint è la fonte di difetti e ritardi.

Posizionate ogni file in un grafico in base alla complessità e al numero di commit degli ultimi sei-dodici mesi. I file in alto a destra sono i vostri hotspot. Strumenti come CodeScene automatizzano il processo, ma anche un semplice script su git log e un report di complessità offrono una prima visione utile in un pomeriggio.

Come si misura la complessità a livello di task?

A livello di task, i team misurano la complessità con stime relative come gli story point, misure funzionali standardizzate come i function point e fattori di complessità espliciti come dipendenze, incertezza e novità. Queste misure catturano rischi che nel codice ancora non esistono.

Story point

Gli story point sono una misura relativa e adimensionale che combina complessità, incertezza e sforzo di un task rispetto ad altri task svolti dallo stesso team. La maggior parte dei team usa una scala di Fibonacci modificata (1, 2, 3, 5, 8, 13), così che gli elementi più grandi portino visibilmente più incertezza.

Gli story point funzionano bene per lo sprint planning all’interno di un team. Non funzionano come misura di produttività tra team diversi, e una ricerca pubblicata nel 2026 ha rilevato che seguono lo sforzo reale più da vicino per le funzionalità pianificate che per i bug fix, dove la complessità nascosta è frequente. Quando un task arriva a 13 punti o più, suddividetelo prima di impegnarvi.

Function point

I function point misurano la dimensione funzionale del software dal punto di vista dell’utente, indipendentemente dal linguaggio di programmazione. La Function Point Analysis IFPUG, standardizzata come ISO/IEC 20926, conta cinque tipi di componenti: input esterni, output esterni, interrogazioni esterne, file logici interni e file di interfaccia esterni.

Ogni componente viene classificato come semplice, medio o complesso e pesato di conseguenza, con un eventuale aggiustamento basato sulle caratteristiche generali del sistema. I function point richiedono più impegno degli story point, ma sono confrontabili tra team e fornitori, ed è per questo che compaiono negli appalti pubblici e nei benchmark di outsourcing. COSMIC (ISO/IEC 19761) è un’alternativa più recente, più adatta al software real-time ed embedded.

Checklist dei fattori di complessità di un task

Una checklist dei fattori di complessità rende espliciti i driver della complessità di un task, così che le stime si basino sui fatti e non sull’intuito. Assegnate a ogni fattore un punteggio da 1 (basso) a 3 (alto) durante il refinement:

1. Complessità del codice nell’area toccata: complessità ciclomatica o cognitiva e stato di hotspot dei file coinvolti.
2. Numero di componenti e servizi coinvolti: ogni modulo, database o API in più aggiunge sforzo di integrazione e di test.
3. Dipendenze esterne: API di terze parti, altri team, approvazioni o rilasci di fornitori fuori dal vostro controllo.
4. Chiarezza dei requisiti: se criteri di accettazione, casi limite e requisiti non funzionali sono messi per iscritto.
5. Novità tecnica: nuovo linguaggio, framework, servizio cloud o algoritmo per il team.
6. Rischio su dati e migrazioni: modifiche di schema, backfill dei dati e retrocompatibilità.
7. Impatto su compliance e sicurezza: trattamento di dati personali, di pagamento o sanitari che richiede revisioni aggiuntive.

Un totale superiore a circa 14 su 21 indica che il task va suddiviso, esplorato con uno spike o preceduto da una breve fase di discovery. La nostra guida alla stima dei progetti software mostra come trasformare questi punteggi in stime a intervallo.

Come si conduce un’analisi della complessità dei task nello sviluppo software?

Per condurre un’analisi della complessità dei task, misurate il codice che il task toccherà, valutate i suoi fattori di complessità, confrontate entrambi con soglie concordate e poi decidete se stimare, suddividere, rifattorizzare prima o fare uno spike. I sei passi seguenti richiedono meno di un’ora per un epic tipico.

1. Mappare la modifica. Elencate file, servizi, archivi dati e integrazioni che il task probabilmente modificherà.
2. Raccogliere le metriche del codice. Eseguite lo strumento di analisi statica su quelle aree e annotate complessità ciclomatica, complessità cognitiva, indice di manutenibilità e copertura dei test.
3. Verificare gli hotspot. Controllate la frequenza delle modifiche e i difetti recenti degli stessi file; un file complesso e modificato spesso è un campanello d’allarme.
4. Valutare i fattori del task. Usate la checklist dei sette fattori insieme agli sviluppatori che faranno il lavoro, non solo con il lead.
5. Confrontare con le soglie. Segnalate ogni funzione oltre i vostri limiti e ogni task con alta incertezza o molte dipendenze.
6. Decidere e documentare. Stimate così com’è, suddividete il task, pianificate un passo di refactoring o uno spike a tempo, e annotate il motivo, così che le retrospettive possano verificare se l’analisi era corretta.

Ripetete l’analisi per gli elementi grandi a ogni refinement. In pochi sprint il team costruisce i propri dati sul rapporto tra punteggi di complessità e cycle time reale, molto più preziosi di qualsiasi benchmark di settore.

Quali punteggi di complessità sono troppo alti?

Una funzione con complessità ciclomatica superiore a 10, complessità cognitiva superiore a 15 o indice di manutenibilità inferiore a 20 sulla scala di Visual Studio merita una revisione, e valori molto più alti di solito giustificano un refactoring. Le soglie sono punti di partenza, non leggi: concordatele nel team e adattatele al vostro linguaggio e dominio.

Lo strumento Python Radon usa una classificazione simile per la complessità ciclomatica: A per 1–5, B per 6–10, C per 11–20, D per 21–30, E per 31–40 e F oltre 40. Codice generato, parser e macchine a stati possono legittimamente superare questi limiti; escludeteli in modo esplicito invece di abbassare l’asticella per tutti.

Come le metriche di complessità prevedono difetti, sforzo e costi?

Le metriche di complessità prevedono difetti, sforzo e costi perché il codice complesso ha più percorsi da testare, più modi di fallire e più contesto da assimilare prima di ogni modifica. Decenni di studi empirici mostrano che la densità dei difetti cresce con la complessità e la frequenza delle modifiche, ed è per questo che i dati sugli hotspot sono una guida così affidabile.

• Difetti: i file con alta complessità e alto churn generano costantemente una quota sproporzionata dei bug in produzione.
• Sforzo: ogni percorso indipendente richiede progettazione, implementazione e un test, quindi la complessità ciclomatica fissa un minimo per lo sforzo di test.
• Lead time: il codice difficile da capire rallenta la code review, aumenta le rilavorazioni e allunga il cycle time.
• Costo della modifica: le funzionalità costruite su moduli complessi richiedono più tempo a ogni release, il che si traduce in un costo crescente per modifica rilasciata.

Usate questi legami come indicatori anticipatori accanto alle metriche di delivery. La nostra guida ai KPI dello sviluppo software spiega come affiancare i trend di complessità a cycle time, change failure rate e difetti sfuggiti.

Quali strumenti misurano la complessità del codice?

La maggior parte dei team misura la complessità del codice con una piattaforma di analisi statica nella CI, una regola di linter specifica per il linguaggio e, per le codebase più grandi, uno strumento di analisi comportamentale che sfrutta la cronologia del controllo di versione. Partite da ciò che si integra nella pipeline esistente.

Qualunque sia lo strumento, eseguitelo su ogni pull request e fate fallire la build solo per le nuove violazioni. Bloccare l’intero debito legacy fin dal primo giorno garantisce che il gate venga disattivato.

Come cambiano le metriche di complessità con gli assistenti di codice IA nel 2026?

Gli assistenti di codice IA rendono le metriche di complessità più importanti, non meno, perché producono codice più velocemente di quanto i team riescano a revisionarlo e spesso preferiscono la duplicazione al riuso. I trend di complessità e duplicazione sono oggi tra i segnali più chiari per capire se il codice generato dall’IA migliora o erode una codebase.

• Aumenta la duplicazione: l’analisi GitClear del 2025 su 211 milioni di righe modificate ha rilevato un forte aumento dei blocchi di codice duplicati nel 2024, in parallelo alla diffusione degli assistenti IA.
• Aumenta l’instabilità: il report DORA 2025 ha rilevato che l’adozione dell’IA è ancora associata a una maggiore instabilità nel rilascio del software.
• Cambia il dimensionamento dei task: il codice boilerplate diventa economico e lo sforzo residuo si concentra su integrazione, casi limite e revisione, aspetti che i fattori di complessità colgono meglio delle righe di codice.

Regole pratiche per il 2026: mantenete i gate di complessità sulle pull request generate dall’IA severi quanto su quelle scritte da persone, monitorate la duplicazione insieme alla complessità cognitiva e chiedete agli assistenti di rifattorizzare le funzioni complesse, non solo di scriverne di nuove. La nostra panoramica sugli strumenti di IA per lo sviluppo software descrive i guardrail che usiamo.

Come ridurre la complessità di task e codice?

Il modo più efficace per ridurre la complessità è suddividere i task grandi, rifattorizzare gli hotspot a piccoli passi e progettare moduli con confini chiari, così che ogni modifica tocchi meno codice possibile. Ridurre la complessità è manutenzione continua, non un progetto di pulizia una tantum.

1. Suddividere i task in verticale: consegnate sottili porzioni di valore per l’utente invece di grandi strati orizzontali, così che ogni task resti sotto gli 8 punti.
2. Estrarre funzioni e usare guard clause: i return anticipati e le funzioni piccole e ben nominate eliminano l’annidamento e riducono rapidamente la complessità cognitiva.
3. Sostituire i condizionali con polimorfismo o tabelle di lookup dove la logica di ramificazione continua a crescere.
4. Rifattorizzare prima gli hotspot: investite il budget di refactoring dove complessità e frequenza delle modifiche si sovrappongono, un po’ a ogni sprint.
5. Ridurre l’accoppiamento: introducete interfacce chiare tra i moduli ed eliminate i cicli di dipendenze.
6. Scrivere test prima del refactoring: i test di caratterizzazione e lo sviluppo guidato dai test rendono sicura la semplificazione.
7. Chiarire presto i requisiti: criteri di accettazione vaghi sono un fattore di complessità a livello di task che nessun codice pulito può correggere.

Le pratiche di qualità si rafforzano a vicenda: code review, test automatizzati e quality gate in CI, descritti nella nostra guida al quality assurance nello sviluppo software, impediscono alla complessità di tornare.

Errori comuni con le metriche di complessità

Gli errori più comuni sono trasformare i punteggi di complessità in obiettivi individuali, affidarsi a una sola metrica, ignorare il contesto e misurare senza agire. Ognuno di questi errori rende i numeri meno affidabili senza rendere il codice più semplice.

• Classificare gli sviluppatori in base alle metriche: le persone manipolano i numeri, ad esempio spezzando meccanicamente le funzioni senza migliorare il design.
• Guardare un solo numero: una bassa complessità ciclomatica con un alto accoppiamento resta codice rischioso.
• Ignorare il contesto: un parser o una macchina a stati può richiedere un’alta complessità; escludeteli consapevolmente.
• Bloccare sul debito legacy: i gate che falliscono sul codice vecchio vengono disattivati; controllate rigorosamente il codice nuovo e migliorate gradualmente quello vecchio.
• Considerare gli story point la verità sulla complessità: i punti sono un aiuto alla pianificazione specifico del team, non una misura oggettiva.
• Misurare senza decidere: se i dati di complessità non cambiano mai una stima, una suddivisione o un piano di refactoring, smettete di raccoglierli.

Domande frequenti

Pubblicato il 5 novembre 2026. Fonti: McCabe, A Complexity Measure (1976); NIST SP 500-235, Structured Testing (1996); SonarSource, white paper Cognitive Complexity; Microsoft, Code metrics values; IFPUG, Function Point Analysis (ISO/IEC 20926); GitClear, AI Copilot Code Quality 2025; DORA, State of AI-assisted Software Development 2025.