Regole esplicite e regole implicite

Le regole sono il cuore del dominio. Dicono che cosa il sistema deve permettere, impedire o mantenere vero.

Il problema è che in un progetto reale le regole non arrivano sempre già scritte bene. A volte qualcuno le dice chiaramente:

Uno strumento guasto non si può prestare.

Questa è una regola esplicita: è detta in modo diretto.

Altre volte la regola è nascosta in una frase più vaga:

Di solito quando torna un kit controlliamo se manca qualcosa.

Qui c’è una regola implicita. Non è formulata come obbligo, ma racconta un comportamento importante del laboratorio.

In questa lezione impariamo a trovare entrambe.

Obiettivo

Alla fine devi avere una lista di regole del Registro del laboratorio divisa in:

• regole esplicite;
• regole implicite;
• regole ancora da chiarire;
• dettagli che non sono regole di dominio.

Questa lista servirà nel modulo sul dominio, quando dovremo trasformare alcune regole in codice e in test.

Che cosa è una regola

Nel nostro percorso una regola è una frase che limita o guida il comportamento del sistema.

Esempi:

Uno strumento guasto non può essere prestato.
Uno strumento già in prestito non può essere prestato di nuovo.
Un prestito chiuso non può essere chiuso una seconda volta.
Ogni strumento deve avere un nome.
Ogni prestito deve riferirsi a uno strumento esistente.

Una regola non è un dettaglio grafico.

Questa non è una regola di dominio:

Il bottone deve essere blu.

Può essere una scelta di interfaccia, ma non descrive il comportamento del laboratorio.

Una buona regola di dominio ha tre caratteristiche:

• parla del laboratorio, non della grafica;
• può essere verificata con un esempio;
• resta valida anche se cambiamo UI o salvataggio.

Esempio:

Uno strumento già in prestito non può essere prestato di nuovo.

Questa regola resta valida sia con una pagina web sia con una CLI. Non dipende dal colore del bottone, dal testo del form o da localStorage.

Regole esplicite

Le regole esplicite sono quelle già formulate in modo abbastanza chiaro.

Possono arrivare da:

• richiesta del docente;
• testo dell’esercizio;
• discussione in classe;
• errore successo durante una prova;
• comportamento già presente nel programma fragile.

Esempio:

Se uno strumento è guasto, non deve comparire tra quelli prestabili.

Questa regola è comprensibile. Possiamo però riscriverla in modo più preciso:

Uno strumento con stato `guasto` non può essere usato per aprire un nuovo prestito.

La seconda versione è più vicina al codice perché nomina stato, prestito e operazione.

Scheda utile:

Frase originale:
Se uno strumento è guasto, non deve comparire tra quelli prestabili.

Regola riscritta:
Uno strumento con stato `guasto` non può essere usato per aprire un nuovo prestito.

Esempio valido:
Strumento disponibile -> prestito consentito.

Esempio non valido:
Strumento guasto -> prestito bloccato.

La regola diventa più utile quando aggiungiamo esempi. Gli esempi, più avanti, potranno diventare test.

Regole implicite

Le regole implicite sono più pericolose perché restano nascoste.

Esempio:

Quando uno studente restituisce uno strumento, il docente lo rimette disponibile.

Domanda:

Sempre?

Forse no. Se lo strumento torna rotto o incompleto, non deve tornare disponibile.

Quindi possiamo estrarre una regola implicita:

Alla chiusura di un prestito, lo stato finale dello strumento deve essere scelto in base alle condizioni dello strumento.

Questa regola non era detta subito, ma cambia il comportamento del sistema.

Le regole implicite spesso emergono da racconti pratici:

Quando il tablet torna, guardiamo se è carico e se ha il caricatore.
Se manca qualcosa, lo teniamo da parte.

Possibili regole:

Alla chiusura di un prestito può essere indicata una nota di restituzione.
Se uno strumento torna incompleto, non deve tornare automaticamente disponibile.
Uno strumento incompleto può essere segnato come in manutenzione.

Non tutte queste regole devono entrare nel progetto base. Però devono essere visibili, così il docente può decidere cosa includere.

Frasi che nascondono regole

Quando senti queste espressioni, fermati:

• “di solito”;
• “normalmente”;
• “non dovrebbe mai”;
• “a meno che”;
• “tranne quando”;
• “solo se”;
• “prima bisogna”;
• “quando succede questo”;
• “se manca qualcosa”;
• “meglio evitare”.

Spesso sono segnali di una regola.

Esempio:

Di solito uno strumento in manutenzione non viene prestato.

Riscrittura:

Uno strumento in manutenzione non può essere prestato.

Se invece “di solito” significa che esistono eccezioni, dobbiamo chiarirle.

Esempio con eccezione:

Di solito uno strumento in manutenzione non viene prestato, a meno che il tecnico lo sblocchi.

Qui non basta scrivere una regola secca. Dobbiamo fare domande:

• chi può sbloccarlo?
• lo sblocco è temporaneo?
• resta una traccia?
• vale per tutti gli strumenti o solo per alcune categorie?

Se non sappiamo rispondere, la regola va nella sezione “da chiarire”.

Regole da chiarire

Non tutte le regole devono essere risolte subito. Alcune vanno segnate come domande.

Esempi:

Uno studente può avere più strumenti in prestito nello stesso momento?
Uno strumento guasto può avere più segnalazioni aperte?
Chi può rimettere disponibile uno strumento in manutenzione?
La data di restituzione è obbligatoria?
Si può cancellare uno strumento che ha prestiti nello storico?

Queste domande sono preziose. Evitano di inventare comportamento a caso.

Una regola incerta non va nascosta nel codice. Se scriviamo una condizione senza aver chiarito la regola, stiamo decidendo al posto del dominio.

Esempio di decisione prematura:

if (prestitiApertiDelloStudente.length >= 1) {
  return "Lo studente ha già un prestito aperto";
}

Questa riga contiene una regola:

Uno studente può avere al massimo un prestito aperto.

Ma chi l’ha decisa? Se nessuno l’ha decisa, va discussa prima.

Dal programma fragile alle regole

Guarda questo codice:

function prestaStrumento(id, studente) {
  const strumento = strumenti.find((item) => item.id === id);

  if (!strumento) {
    alert("Strumento non trovato");
    return;
  }

  if (strumento.stato !== "disponibile") {
    alert("Strumento non disponibile");
    return;
  }

  prestiti.push({
    id: crypto.randomUUID(),
    strumentoId: id,
    studente,
    aperto: true,
  });

  strumento.stato = "in_prestito";
}

Da questo codice possiamo estrarre regole:

• il prestito richiede uno strumento esistente;
• lo strumento deve essere disponibile;
• aprire un prestito cambia lo stato dello strumento;
• un prestito aperto deve avere un identificativo;
• il prestito deve memorizzare lo studente.

Il codice non è ancora ben organizzato, ma contiene conoscenza del dominio. Il nostro lavoro è portarla alla luce.

Possiamo anche separare ciò che è dominio da ciò che è UI:

Regola di dominio:
- lo strumento deve essere disponibile

Dettaglio di UI:
- viene usato alert per mostrare l'errore

Dettaglio tecnico:
- l'id del prestito viene creato con crypto.randomUUID()

Questa separazione ci impedisce di mettere tutto nello stesso sacco.

Scheda regole

Compila una scheda come questa:

# Regole del Registro del laboratorio

## Regole esplicite

- ...

## Regole implicite individuate

- Frase originale:
  Regola riscritta:

## Regole da chiarire

- Domanda:
  Perché è importante:

## Regole escluse dal dominio

- ...

L’ultima sezione serve a non confondere tutto.

Esempio di regola esclusa dal dominio:

Il messaggio di successo deve essere verde.

È una scelta di UI, non una regola del laboratorio.

Esempio compilato

# Regole del Registro del laboratorio

## Regole esplicite

- Uno strumento guasto non può essere prestato.
- Uno strumento già in prestito non può essere prestato di nuovo.
- Un prestito chiuso non può essere chiuso una seconda volta.

## Regole implicite individuate

- Frase originale:
  Quando torna un kit, controlliamo se manca qualcosa.
  Regola riscritta:
  Alla chiusura del prestito deve essere possibile indicare lo stato finale dello strumento.

## Regole da chiarire

- Domanda:
  Uno studente può avere più prestiti aperti?
  Perché è importante:
  Cambia la validazione di RegistraPrestito.

## Regole escluse dal dominio

- Il messaggio di successo deve essere verde.
- La lista deve avere card con bordo arrotondato.

Esercizio guidato

Prendi queste frasi e trasformale in regole:

1. Se il proiettore è rotto, non lo diamo a nessuno.
2. Quando torna un dispositivo, prima controlliamo che sia tutto intero.
3. Gli strumenti senza nome creano confusione.
4. Non vogliamo perdere i prestiti vecchi.
5. Se uno studente non restituisce il kit, deve restare segnato.

Possibili riscritture:

1. Uno strumento con stato guasto non può essere prestato.
2. Alla chiusura di un prestito deve essere indicato lo stato finale dello strumento.
3. Uno strumento deve avere un nome non vuoto.
4. La chiusura di un prestito non cancella il prestito dallo storico.
5. Un prestito resta aperto finché non viene registrata una restituzione.

Poi aggiungi un esempio per ogni regola:

Regola:
Uno strumento con stato guasto non può essere prestato.

Esempio che passa:
Microscopio disponibile -> prestito registrato.

Esempio che fallisce:
Proiettore guasto -> prestito bloccato.

Questo passaggio prepara il lavoro sui test.

Mini-catalogo iniziale

Per il Registro del laboratorio possiamo partire da questo catalogo:

## Strumenti

- Ogni strumento deve avere un nome non vuoto.
- Ogni strumento deve avere una categoria.
- Ogni strumento deve avere uno stato valido.

## Prestiti

- Un prestito deve riferirsi a uno strumento esistente.
- Un prestito aperto deve indicare a chi è stato assegnato lo strumento.
- Un prestito chiuso non può essere chiuso di nuovo.

## Stati

- Uno strumento guasto non può essere prestato.
- Uno strumento in manutenzione non può essere prestato.
- Uno strumento già in prestito non può essere prestato di nuovo.

## Segnalazioni

- Una segnalazione deve riferirsi a uno strumento esistente.
- Una segnalazione deve avere una descrizione non vuota.
- Aprire una segnalazione di guasto rende lo strumento non prestabile.

Non è definitivo. È una base da discutere e correggere.

Cosa produrre

Alla fine della lezione devi avere:

• almeno cinque regole esplicite;
• almeno tre regole implicite;
• almeno tre domande da chiarire;
• almeno due esempi di cose che non sono regole di dominio;
• una lista pronta da usare nel modulo sul dominio.

Domande di comprensione

Rispondi per iscritto:

• Qual è la differenza tra regola esplicita e regola implicita?
• Perché una regola incerta non dovrebbe essere nascosta direttamente nel codice?
• Quale frase del laboratorio contiene un “di solito” o un “a meno che”?
• Quale dettaglio della UI non è una regola di dominio?
• Quale regola del Registro è già pronta per diventare un test?

Controllo finale

La lezione è completata quando puoi rispondere sì:

• so distinguere una regola da un dettaglio di UI;
• ho trovato regole nel testo e nel codice;
• ho riscritto frasi vaghe in frasi verificabili;
• ho segnato le regole incerte come domande;
• non ho inventato risposte quando mancavano informazioni.

Nella prossima lezione guardiamo i vincoli pratici del laboratorio scolastico.