149 lines
8.6 KiB
Markdown
149 lines
8.6 KiB
Markdown
# 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. |