# 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? 1. **Contare:** Sapere quante righe di codice, commenti e righe vuote compongono il tuo progetto. 2. **Misurare:** Calcolare la complessità e la manutenibilità del software. 3. **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. 1. **Top Bar (Barra Superiore):** * Selezione del **Profilo**. * Accesso alle impostazioni (**Settings**) e gestione profili (**Manage**). 2. **Actions Bar (Azioni):** I pulsanti principali per avviare le operazioni (`Scan`, `Countings`, `Metrics`, `Differing`). 3. **Progress Area:** Barra di avanzamento e contatore dei file elaborati. 4. **Results Table:** La grande tabella centrale dove appaiono i dati. 5. **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. 1. Clicca su **⚙️ Manage...** in alto. 2. Clicca su **📝 New** per pulire i campi. 3. Inserisci un **Nome** per il profilo (es. "Mio Progetto Backend"). 4. Nella sezione **Paths**, usa **Add Folder** per selezionare la cartella radice del tuo codice. 5. Nella sezione **Filter Extensions**, seleziona i linguaggi che ti interessano (es. Python, Java). 6. Nella casella **Ignore patterns**, puoi lasciare i default (che escludono già `.git`, `__pycache__`, ecc.). 7. 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** 1. Seleziona il tuo profilo. 2. Clicca su **🔀 Differing**. 3. Se è la prima volta che analizzi questo progetto, PyUCC ti avviserà: *"No baseline found"*. 4. 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** 1. Riapri PyUCC e seleziona lo stesso profilo. 2. Clicca su **🔀 Differing**. 3. Questa volta, PyUCC vedrà che esiste una Baseline precedente e ti chiederà con quale confrontare (se ne hai più di una). 4. 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: 1. **Core (`pyucc.core`):** Contiene la logica pura (scansione, calcolo metriche, algoritmi di diff). Non sa nulla dell'interfaccia grafica. 2. **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.