VALLONGOL 79ed9c1d72 aggiornato manuale e readme

2025-12-05 11:23:44 +01:00

12 KiB

Raw Permalink Blame History

Manuale Utente PyUCC

Versione Documento: 1.0 Applicazione: PyUCC (Python Unified Code Counter)

1. Introduzione

PyUCC è uno strumento avanzato per l'analisi statica del codice sorgente. Il suo obiettivo principale è fornire metriche quantitative sullo sviluppo software e, soprattutto, tracciare l'evoluzione del codice nel tempo attraverso un potente sistema di Differing (confronto).

A cosa serve?

Contare: Sapere quante righe di codice, commenti e righe vuote compongono il tuo progetto.
Misurare: Calcolare la complessità e la manutenibilità del software.
Confrontare: Capire esattamente cosa è cambiato tra due versioni (file aggiunti, rimossi, modificati e come la complessità è variata).

2. Concetti Fondamentali

Prima di iniziare, è utile comprendere i termini chiave utilizzati nell'applicazione.

2.1 Baseline

Una Baseline è una "fotografia" istantanea del tuo progetto in un preciso momento.

Quando crei una baseline, PyUCC salva una copia dei file e calcola tutte le metriche.
Le baseline servono come punto di riferimento (o "pietra di paragone") per i confronti futuri.

2.2 Metriche Supportate

SLOC (Source Lines of Code):
- Physical Lines: Totale righe del file.
- Code Lines: Righe che contengono codice eseguibile.
- Comment Lines: Righe di documentazione.
- Blank Lines: Righe vuote (spesso usate per formattazione).
Complessità Ciclomatica (CC): Misura quanto è complesso il flusso di controllo (quanti if, for, while, ecc.). Più è bassa, meglio è.
Maintainability Index (MI): Un indice da 0 a 100 che stima quanto il codice sia facile da mantenere. Più è alto, meglio è (sopra 85 è ottimo, sotto 65 è problematico).

2.3 Profilo

Un Profilo è una configurazione salvata che dice a PyUCC:

Quali cartelle analizzare.
Quali linguaggi includere (es. solo Python e C++).
Cosa ignorare (es. cartelle venv, build, file temporanei).

3. Interfaccia Utente (GUI)

L'interfaccia è divisa in zone funzionali per mantenere il flusso di lavoro ordinato.

Top Bar (Barra Superiore):
- Selezione del Profilo.
- Accesso alle impostazioni (Settings) e gestione profili (Manage).
Actions Bar (Azioni): I pulsanti principali per avviare le operazioni (Scan, Countings, Metrics, Differing).
Progress Area: Barra di avanzamento e contatore dei file elaborati.
Results Table: La grande tabella centrale dove appaiono i dati.
Log & Status: In basso, un pannello di log per vedere cosa sta succedendo e una barra di stato con il monitoraggio risorse (CPU/RAM).

4. Guida Passo-Passo

4.1 Primo Avvio e Configurazione Profilo

Non appena apri PyUCC, la prima cosa da fare è dire al programma cosa analizzare.

Clicca su ⚙️ Manage... in alto.
Clicca su 📝 New per pulire i campi.
Inserisci un Nome per il profilo (es. "Mio Progetto Backend").
Nella sezione Paths, usa Add Folder per selezionare la cartella radice del tuo codice.
Nella sezione Filter Extensions, seleziona i linguaggi che ti interessano (es. Python, Java).
Nella casella Ignore patterns, puoi lasciare i default (che escludono già .git, __pycache__, ecc.).
Clicca 💾 Save.

4.2 Analisi Semplice (Scan, Countings, Metrics)

Se vuoi solo analizzare lo stato attuale senza confronti:

🔍 Scan: Verifica semplicemente quali file vengono trovati in base ai filtri del profilo. Utile per controllare se stai includendo i file giusti.
🔢 Countings: Analizza ogni file e ti dice quante righe di codice, commenti e vuote ci sono.
📊 Metrics: Calcola la complessità ciclomatica e l'indice di manutenibilità per ogni file.

Tip: Puoi fare doppio click su un file nella tabella dei risultati per aprirlo nel File Viewer integrato, che evidenzia la sintassi e mostra una minimappa colorata (blu=codice, verde=commenti).

4.3 Il Flusso di Lavoro "Differing" (Confronto)

Questa è la funzione più potente di PyUCC.

Passo A: Creare la prima Baseline

Seleziona il tuo profilo.
Clicca su 🔀 Differing.
Se è la prima volta che analizzi questo progetto, PyUCC ti avviserà: "No baseline found".
Conferma la creazione. PyUCC scatterà una "foto" del progetto (Baseline).

Passo B: Lavorare sul codice Ora puoi chiudere PyUCC e lavorare al tuo codice (modificare file, aggiungerne, cancellarne).

Passo C: Confrontare

Riapri PyUCC e seleziona lo stesso profilo.
Clicca su 🔀 Differing.
Questa volta, PyUCC vedrà che esiste una Baseline precedente e ti chiederà con quale confrontare (se ne hai più di una).
Il risultato sarà una tabella con colori specifici:
- Verde: File aggiunti o metriche migliorate.
- Rosso: File cancellati o metriche peggiorate (es. complessità aumentata).
- Giallo/Arancio: File modificati.
- Colonne Δ (Delta): Mostrano la differenza numerica (es. +50 righe di codice, -2 complessità).

Visualizzatore Differenze: Se fai doppio click su una riga nel risultato del Differing, si aprirà una finestra che mostra i due file affiancati, evidenziando esattamente le righe cambiate.

5. Casi d'Uso Esemplificativi

Caso 1: Refactoring del codice

Obiettivo: Vuoi pulire il codice e assicurarti di non aver aumentato la complessità.
Azione: Fai una Baseline prima di iniziare. Fai il refactoring. Esegui il Differing.
Verifica: Controlla la colonna Δ avg_cc. Se è negativa (es. -0.5), ottimo! Hai ridotto la complessità. Se la colonna Δ comment_lines è positiva, hai migliorato la documentazione.

Caso 2: Code Review

Obiettivo: Un collega ha aggiunto una nuova feature. Cosa è cambiato?
Azione: Esegui il Differing rispetto alla versione master precedente.
Verifica: Ordina per "Status". Vedi subito i file Added (A) e Modified (M). Apri il Diff Viewer sui file modificati per vedere le righe esatte.

6. Filosofia di Sviluppo (Per Sviluppatori)

PyUCC è stato scritto seguendo principi di ingegneria del software rigorosi, che si riflettono nella stabilità dell'uso.

6.1 Codice Pulito e Standard PEP8

Il codice rispetta lo standard PEP8 di Python. Questo garantisce che, se un giorno volessi estendere il tool o scriverne degli script di automazione usando i moduli core, troveresti un codice leggibile, standardizzato e prevedibile.

6.2 Separazione delle Responsabilità (SoC)

L'applicazione è divisa nettamente in due parti:

Core (pyucc.core): Contiene la logica pura (scansione, calcolo metriche, algoritmi di diff). Non sa nulla dell'interfaccia grafica.
GUI (pyucc.gui): Gestisce solo la visualizzazione. Filosofia: Questo permette di cambiare la grafica senza rompere la logica, o usare la logica da riga di comando senza avviare la grafica.

6.3 Non-Blocking UI (Worker Manager)

Hai notato che l'interfaccia non si blocca mai, anche analizzando migliaia di file? Questo è grazie al WorkerManager. Tutte le operazioni pesanti vengono eseguite in thread separati (background). L'interfaccia grafica riceve aggiornamenti tramite una coda sicura (queue).

Per l'utente significa: Puoi sempre premere "Cancel" se un'operazione è troppo lunga.

6.4 Algoritmo di Matching Intelligente (Gale-Shapley)

Nel Differing, PyUCC non guarda solo se il nome del file è identico. Usa un algoritmo ispirato al "problema del matrimonio stabile" (Gale-Shapley) combinato con la distanza di Levenshtein sui percorsi.

Filosofia: Se sposti un file da una cartella all'altra, il sistema cerca di capire che è lo stesso file spostato, invece di segnarne uno come "Deleted" e uno come "Added".

6.5 Determinismo

Il sistema usa l'hashing (SHA1/MD5) del contenuto dei file per ottimizzare i calcoli (caching) e per determinare se un file è veramente cambiato, ignorando la data di modifica del file system se il contenuto è identico.

7. Risoluzione Problemi Comuni

Il programma non trova file: Controlla nel Profile Manager se l'estensione del file è nella lista dei linguaggi o se la cartella è inclusa negli "Ignore patterns".
Lentezza estrema: Se hai incluso cartelle con migliaia di file piccoli non di codice (es. node_modules o cartelle di immagini), aggiungile agli "Ignore patterns".
Diff Viewer vuoto: Assicurati che i file sorgente esistano ancora sul disco. Se hai cancellato la cartella del progetto dopo aver fatto la baseline, il viewer non potrà mostrare il file corrente.

8. Nuove Funzionalità (Da v1.0)

Questa release introduce funzionalità che migliorano l'analisi della qualità del codice, la riproducibilità delle baseline e la ricerca di duplicazioni nel codice. Di seguito una descrizione sintetica delle novità e come usarle.

8.1 Rilevamento Duplicati (GUI + CLI)

Cosa fa: Individua duplicati esatti e fuzzy all'interno del progetto. I duplicati esatti sono individuati tramite hashing del contenuto (SHA1). I duplicati fuzzy usano fingerprinting a k-gram con una fase di winnowing e una misura di similarità Jaccard per identificare coppie simili.
Parametri: k (dimensione dei k-gram), window (finestra di winnowing) e threshold (soglia di similarità in percentuale). I valori di default sono bilanciati per precisione/recall ma possono essere modificati dall'utente.
Esecuzione (GUI): Usa il nuovo pulsante Duplicates nella barra Azioni (posizionato prima del pulsante Differ). Una finestra di dialogo permette di scegliere estensioni, soglia e parametri di fingerprinting. Le impostazioni sono persistenti.
Esecuzione (CLI): python -m pyucc duplicates <path> --threshold 5.0 --ext .py .c stampa in output JSON i duplicati trovati.
Esportazione: Risultati esportabili in CSV e in un report testuale in stile UCC inserito nella cartella baseline (quando eseguito durante la creazione della baseline).

8.2 Report UCC-style per Duplicati e Differenze

Tabella compatta in stile UCC: Il differ ora può generare una tabella compatta simile all'output UCC, con colonne Δ (delta) aggiuntive: ΔCode, ΔComm, ΔBlank, ΔFunc, ΔAvgCC, ΔMI, per vedere rapidamente le variazioni numeriche.
Report duplicati: Viene creato un file testuale duplicates_report.txt (se richiesto) che elenca i gruppi di duplicati con la similarità percentuale e i parametri usati. Le baseline salvano i parametri per garantire la riproducibilità.

Esempio (snippet compatto in stile UCC):

File                                   Code   Comm  Blank  Func  AvgCC   MI   ΔCode  ΔComm  ΔBlank  ΔFunc  ΔAvgCC  ΔMI
---------------------------------------------------------------------------------------------------------------
src/module/a.py                         120    10     8      5     2.3    78   +10    -1     0       +0     -0.1    +2
src/module/b_copy.py                    118     8     10     5     2.4    76   -2     -2     +2      0      +0.1   -2

8.3 Scanner e Migliorie alle Baseline

Scansione centralizzata: Lo scanner è il fornitore canonico della lista file. Moduli pesanti (Differ, Duplicates) possono ricevere la file_list prodotta dallo scanner per evitare ricerche ripetute e garantire lo stesso filtro.
Normalizzazione dei pattern di ignore: Voci di ignore come .bak vengono normalizzate in *.bak e il matching è case-insensitive per default; questo evita di includere file di backup nelle baseline.
Riproducibilità delle baseline: Le baseline memorizzano i parametri usati per la ricerca duplicati e la lista dei file snapshot. Se in seguito viene installato lizard, PyUCC tenta di rieseguire l'analisi per ottenere informazioni sulle funzioni anche nelle baseline create in precedenza.

8.4 Note sulle Dipendenze

Le metriche a livello di funzione (numero di funzioni, CC per funzione) richiedono lizard. Se lizard non è installato, PyUCC produrrà comunque SLOC e metriche di base, ma i dettagli per funzione potrebbero mancare. La creazione della baseline registra questo stato e tenterà una rianalisi se lizard diventa disponibile.

Se vuoi, posso aggiungere un esempio passo-passo che mostra come creare una baseline, eseguire la ricerca duplicati e esportare CSV + report UCC sia da GUI che da CLI. Vuoi che lo prepari con comandi e file di esempio?

12 KiB Raw Permalink Blame History