8.6 KiB
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.
+50righe di codice,-2complessità).
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_moduleso 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.