Cultura di Code Review: Qualità Misurabile, Nessun Conflitto Personale

I processi di code review generalmente iniziano come "controllo qualità" e finiscono come "battaglia dell'ego". Man mano che il team cresce, due trappole diventano evidenti: i PR rimangono in sospeso per settimane oppure ogni commento viene percepito come critica personale. Entrambe derivano dallo stesso problema di fondo — regole non misurabili. In 8 anni presso Roibase, lavorando con più di 15 persone da discipline diverse, abbiamo imparato qualcosa di semplice: se non ancorate la cultura di review a criteri numerici, il giudizio personale diventa inevitabile. Quando trasformate metriche come time-to-review, comment density e PR size in sistema, la qualità aumenta e i conflitti diminuiscono.

Velocità di Review: SLA su Time-to-Review

Ogni PR ha un ciclo di vita. Il tempo che passa dall'apertura al primo commento — time-to-first-review — è il primo indicatore della disciplina del team. Presso Roibase abbiamo limitato questo tempo a massimo 4 ore (durante le ore di lavoro). Perché 4 ore? È il punto ideale tra preservare i blocchi di deep work e accelerare il ciclo di feedback in un modello di lavoro asincrono.

La regola è questa: entro 4 ore dall'apertura di un PR, almeno un reviewer deve esaminarla. Il meccanismo di enforcement non è una notifica Slack — è un workflow GitHub Actions. Quando un PR viene aperto, viene automaticamente etichettato e dopo 4 ore i reviewer assegnati ricevono una menzione Slack. Questo soft reminder elimina le review dimenticate.

La metrica time-to-merge è più critica. Il tempo totale dall'apertura del PR al merge nel branch main — ad esempio, i cambiamenti backend non dovrebbero superare 24 ore. Per i frontend, 48 ore. Perché questa differenza? I merge backend generalmente richiedono meno approvazioni visive e possono essere deployati dietro feature flag. Sul frontend, il QA del design e i test cross-device richiedono tempo.

Dashboard delle Metriche: Integrazione con Linear

Integriamo Linear con GitHub in modo che ogni PR venga automaticamente collegato a un ticket Linear. Lo stato del ticket si aggiorna in base al ciclo di vita della PR. Alla fine dello sprint, guardiamo il numero: time-to-merge medio. Se la media del team supera le 36 ore, è un segnale che c'è un problema da affrontare nella retrospettiva — generalmente causato da PR troppo grandi o carico dei reviewer.

PR Size: Regola dei 400 Righe

I PR grandi non possono essere revisionati adeguatamente. È il consensus più diffuso del settore, ma raramente viene trasformato in regola misurabile. Lo standard Roibase è: massimo 400 righe di cambiamenti (addizioni + eliminazioni combinate). Da dove viene questo numero? È la quantità di righe che un reviewer può ragionevolmente mantenere in contesto mentale durante una review mirata di 30 minuti.

Per enforcing la regola usiamo una branch protection rule di GitHub: i PR che superano 400 righe ricevono automaticamente l'etichetta "needs-split" e non possono essere mergiati. Ci sono eccezioni — aggiornamenti di dipendenze, script di migrazione — ma anche queste richiedono un override manuale con justification in un commento GitHub.

Come si gestiscono i grandi refactor? Con stacked PR. Il primo PR: cambio dell'interfaccia; il secondo PR: implementation; il terzo PR: rimozione del codice vecchio. Ognuno sotto le 400 righe, ognuno revisionabile indipendentemente. Questo approccio richiede tempo? Sì. Il rischio di merge conflict aumenta un po'? Certamente. Ma la qualità della review migliora esponenzialmente — perché il reviewer ha la capacità mentale per pensare a ogni cambiamento.

# GitHub Actions — PR size check
name: PR Size Check
on: pull_request

jobs:
  size_check:
    runs-on: ubuntu-latest
    steps:
      - name: Check PR size
        run: |
          ADDITIONS=$(jq '.pull_request.additions' "$GITHUB_EVENT_PATH")
          DELETIONS=$(jq '.pull_request.deletions' "$GITHUB_EVENT_PATH")
          TOTAL=$((ADDITIONS + DELETIONS))
          if [ $TOTAL -gt 400 ]; then
            echo "PR too large: $TOTAL lines"
            gh pr edit --add-label needs-split
            exit 1
          fi

Comment Density: Limite dei Nitpick

Non tutti i commenti hanno lo stesso peso. C'è una differenza critica tra "questo potrebbe essere refactorizzato" e "questo causa un null pointer exception". Nel template di review Roibase, le categorie di commenti sono obbligatorie:

Categoria	Etichetta	Esempio
Blocker	`🔴 BLOCKER`	Falla di sicurezza, crash runtime
Major	`🟠 MAJOR`	Regressione di performance, errore di logica
Minor	`🟡 MINOR`	Convenzione di naming, code coverage
Nitpick	`🔵 NITPICK`	Questione di preferenza, soggettivo

La regola: il rapporto nitpick non deve superare il 30%. Se una PR ha 10 commenti, 3 possono essere nitpick, gli altri devono essere blocker/major/minor. Perché? Perché le review ricche di nitpick demotivano l'autore, e il reviewer viene percepito come inutilmente meticoloso.

La metrica comment density: numero medio di commenti per PR. Presso Roibase questo numero è 3-5. Sopra 10 commenti generalmente indica che la PR dovrebbe essere divisa. Zero commenti è un segnale di rubber stamp review — cosa indesiderata.

Uso del Template

Ogni reviewer parte dal template di PR GitHub:

## Review Checklist
- [ ] La logica del codice è corretta?
- [ ] La code coverage è sopra l'80%?
- [ ] Ci sono breaking change? (CHANGELOG aggiornato?)
- [ ] È stato misurato l'impatto sulla performance? (benchmarks/)

## Comments
**🔴 BLOCKER:**
-

**🟠 MAJOR:**
-

**🟡 MINOR:**
-

**🔵 NITPICK:**
-

Questo template serve due scopi: forza il reviewer a categorizzare, e l'autore vede subito quali commenti sono critici.

Review Asincrona: Trappola dei Meeting Sincroni

Le code review non dovrebbero svolgersi in meeting sincroni. Presso Roibase non esiste il concetto di "review call" — tutte le review sono asincrone, su GitHub. Perché? Perché il team lavora in 3 timezone diverse, e preservare i blocchi di deep work è critico.

La disciplina della review asincrona funziona così: il reviewer esamina la PR durante il suo blocco di deep focus (generalmente 09:00-12:00). Scrive i commenti, approva o richiede cambiamenti. L'autore riceve la notifica (nel suo calendario) e apporta le modifiche, ri-richiedendo la review. Questo ciclo si ripete mediamente 2-3 volte.

Eccezione: deadlock di review — se l'autore e il reviewer non riescono a mettersi d'accordo in 3 cicli di scambi, allora si apre una call sincrona di 15 minuti. Ma questo accade 5-6 volte all'anno, come eccezione. La voce del brand che Roibase ha creato durante il suo processo di branding riflette questa cultura del lavoro async-first — documentazione-first, meeting-last.

Ownership vs. Gatekeeping

Lo scopo della code review è garantire la qualità, ma l'effetto collaterale non dovrebbe essere il gatekeeping. Presso Roibase ogni PR richiede minimo 1, massimo 2 reviewer. Perché 2 come limite massimo? Perché aspettare l'approvazione di 3+ reviewer ha un costo in termini di tempo che supera il guadagno in qualità del codice.

La selezione dei reviewer non è automatica — è l'autore a scegliere. La regola: almeno uno deve essere code owner (dal file CODEOWNERS), l'altro può essere chiunque. Questo approccio mantiene l'ownership nell'autore. La domanda "chi dovrebbe approvare?" è responsabilità dell'autore, non del leader del team.

Il file CODEOWNERS è così strutturato:

# Backend
/backend/ @backend-team
/api/ @backend-team

# Frontend
/web/ @frontend-team
/mobile/ @mobile-team

# Infrastructure
/terraform/ @devops-team
/.github/ @devops-team

Ogni cambio di file deve essere revisionato da uno del team competente — ma è sempre l'autore a scegliere la persona.

Retrospettiva: Metriche di Review

Ogni fine sprint (ogni 2 settimane) esaminiamo le metriche di review. Dashboard Linear:

Time-to-merge medio (target: 36 ore)
Distribuzione della PR size (target: 90% sotto 400 righe)
Comment density (target: 3-5 per PR)
Rapporto nitpick (target: <30%)
Bottleneck di review (quale reviewer accumula più attese?)

Questi numeri vengono discussi nella retrospettiva senza assegnazione personale di colpe. Ad esempio, invece di "Ali fa review lente", la domanda è "I PR backend attendono in media 48 ore, dovremmo ampliare il pool di reviewer?"

Trasformare la cultura di code review da giudizio personale a disciplina sistemica non è difficile — ma richiede regole misurabili. SLA su time-to-review, regola dei 400 righe, categorizzazione dei commenti, approccio async-first — questi sono gli strumenti concreti che presso Roibase mantengono la qualità mentre il team cresce in 8 anni. Se i vostri processi di review sono ancora "intuitivi" e "caso per caso", inserite i numeri, trasformateli in sistema. La qualità aumenterà mentre i conflitti diminuiranno.