Glossario del dominio: parole da usare nel codice

Il glossario del dominio è una lista di parole importanti del progetto.

Non è un dizionario elegante. È uno strumento pratico per evitare codice confuso.

Se in un file scriviamo tool, in un altro device, in un altro strumento, in un altro materiale, il progetto diventa più difficile da leggere.

Nel nostro corso scegliamo parole chiare e le usiamo con coerenza.

Obiettivo

Alla fine devi avere un glossario del Registro del laboratorio con:

• termini principali;
• definizioni brevi;
• esempi;
• parole da evitare;
• nomi consigliati per il codice;
• prime relazioni tra i termini.

Questo glossario aiuterà a nominare dominio, casi d’uso, file e test.

Perché il glossario è architettura

Sembra una cosa linguistica, ma è architettura.

I nomi creano confini.

Se chiami tutto item, non sai più se stai parlando di:

• strumento;
• prestito;
• segnalazione;
• riga della tabella;
• dato salvato in localStorage;
• oggetto ricevuto da una futura API.

Un nome preciso riduce confusione.

Esempio debole:

const item = items.find((item) => item.id === id);

Il codice funziona, ma non spiega.

Meglio:

const strumento = strumenti.find((strumento) => strumento.id === id);

Ancora meglio, quando arriveremo ai casi d’uso:

const strumento = archivioStrumenti.trovaPerId(strumentoId);

La parola strumento racconta il dominio. La parola archivioStrumenti racconta il confine con i dati.

Scelta della lingua

In questo corso usiamo termini italiani per il dominio:

strumento
prestito
segnalazioneGuasto
statoStrumento
archivioStrumenti

Possiamo usare inglese per parole tecniche comuni quando servono, come localStorage, DTO, adapter, test. Ma il cuore del Registro resta in italiano.

La regola pratica è:

Se la parola appartiene al problema del laboratorio, usiamo il linguaggio del laboratorio.
Se la parola appartiene alla tecnologia, usiamo il termine tecnico corretto.

Termini principali

Partiamo da una lista operativa. Non deve essere perfetta al primo colpo: deve essere abbastanza chiara da guidare il codice.

Strumento

Uno strumento è un oggetto o dispositivo presente nel laboratorio.

Esempi:

• Arduino Uno;
• kit sensori;
• multimetro;
• proiettore;
• notebook;
• stampante 3D;
• saldatore.

Nel codice useremo:

strumento
strumenti
Strumento

Evitiamo sinonimi casuali:

tool
device
materiale
oggetto
item

Relazioni:

• uno strumento ha uno stato;
• uno strumento può avere prestiti;
• uno strumento può avere segnalazioni di guasto.

Categoria

La categoria raggruppa strumenti simili.

Esempi:

• robotica;
• elettronica;
• audio;
• video;
• reti;
• misura;
• stampa 3D.

Nel codice:

categoria

Nella prima versione può essere una stringa. Più avanti, se serve, potrà diventare una lista controllata.

StatoStrumento

Lo stato indica la condizione corrente dello strumento.

Stati principali:

disponibile
in_prestito
guasto
in_manutenzione

Lo stato non è solo testo da mostrare. Influenza le regole.

Esempio:

Solo uno strumento disponibile può essere prestato.

Nel codice:

const StatoStrumento = {
  DISPONIBILE: "disponibile",
  IN_PRESTITO: "in_prestito",
  GUASTO: "guasto",
  IN_MANUTENZIONE: "in_manutenzione",
};

Non serve introdurre subito enum complessi. L’importante è evitare stringhe sparse ovunque.

Prestito

Un prestito rappresenta l’assegnazione temporanea di uno strumento a una persona o gruppo.

Un prestito ha un ciclo di vita:

aperto -> chiuso

Dati tipici:

• id;
• strumentoId;
• studente o gruppo;
• dataInizio;
• dataChiusura;
• stato del prestito;
• note.

Nel codice:

prestito
prestiti
Prestito

Da non confondere con lo strumento. Lo strumento è la cosa. Il prestito è il rapporto temporaneo.

PrestitoAperto e PrestitoChiuso

Non sempre serviranno come tipi separati, ma sono concetti utili.

Un prestito aperto:

• non ha data di chiusura;
• indica che lo strumento non è disponibile;
• può essere chiuso.

Un prestito chiuso:

• ha data di chiusura;
• non può essere chiuso di nuovo;
• resta nello storico.

Questa distinzione aiuta a scrivere regole più chiare.

Studente o gruppo

Nel Registro lo studente è la persona o il gruppo a cui viene assegnato uno strumento.

Attenzione: lo studente può comparire nei dati anche se non usa direttamente l’applicazione.

Nel codice useremo:

studente
gruppo
assegnatario

Scegli una parola principale. Per il percorso base useremo spesso studente, ma assegnatario può essere utile se il prestito può andare anche a gruppi o docenti.

SegnalazioneGuasto

Una segnalazione di guasto descrive un problema rilevato su uno strumento.

Dati tipici:

• id;
• strumentoId;
• descrizione;
• data;
• segnalatoDa;
• stato della segnalazione.

Nel codice:

segnalazioneGuasto
segnalazioniGuasto
SegnalazioneGuasto

Possiamo abbreviare in segnalazione solo se nel progetto non esistono altri tipi di segnalazione.

Manutenzione

La manutenzione indica che uno strumento non è disponibile perché deve essere controllato, riparato o completato.

Non è sinonimo perfetto di guasto:

guasto:
  lo strumento ha un problema rilevato

in_manutenzione:
  lo strumento è in fase di controllo o riparazione

Questa differenza evita regole confuse. Uno strumento guasto e uno in manutenzione non sono prestabili, ma raccontano situazioni diverse.

Archivio

Un archivio è il componente che conserva e recupera dati.

Nella prima versione può essere in memoria.

Poi può usare:

• localStorage;
• file JSON;
• database;
• API.

Nel codice useremo nomi come:

archivioStrumenti
archivioPrestiti
ArchivioStrumenti

Il termine archivio è didatticamente utile per parlare di persistenza senza entrare subito in database, repository pattern o strumenti avanzati.

Caso d’uso

Un caso d’uso rappresenta una operazione significativa del sistema.

Esempi:

RegistraStrumento
CercaStrumenti
RegistraPrestito
ChiudiPrestito
ApriSegnalazioneGuasto

Nel codice potrà essere una funzione o una classe, a seconda dello stile scelto. Nella prima parte del corso useremo funzioni chiare.

DTO

Un DTO è un oggetto usato per trasportare dati verso l’esterno o dall’esterno.

Nel nostro corso lo incontreremo quando salveremo dati in localStorage, JSON o API.

Esempio:

const strumentoDto = {
  id: "str-1",
  nome: "Arduino Uno",
  categoria: "elettronica",
  stato: "disponibile",
};

Il DTO non deve diventare automaticamente il modello del dominio. Può avere forma simile, ma ha una responsabilità diversa.

Glossario operativo

Crea o aggiorna un file:

docs/glossario.md

Usa questa struttura:

# Glossario del Registro del laboratorio

## Termine

Definizione:

Esempi:
- ...

Nel codice useremo:
- ...

Da evitare:
- ...

Relazioni:
- ...

Ripeti la scheda per tutti i termini principali.

Collegare glossario e nomi dei file

Il glossario deve aiutarti a scegliere nomi come:

domain/strumento.js
domain/statoStrumento.js
domain/prestito.js
application/registraPrestito.js
application/cercaStrumenti.js
infrastructure/archivioStrumentiInMemoria.js

Questi nomi sono più leggibili di:

utils.js
manager.js
handler.js
data.js
stuff.js

I nomi generici sembrano comodi all’inizio, ma fanno perdere orientamento.

Esercizio: trova sinonimi pericolosi

Guarda il tuo programma fragile.

Cerca parole diverse che indicano lo stesso concetto.

Esempi:

device, tool, strumento
loan, prestito, assegnazione
broken, guasto, errore
available, libero, disponibile

Scegli una parola principale e annota le altre come da evitare.

Esempio:

Concetto:
strumento

Parola scelta:
strumento

Sinonimi da evitare:
tool, device, item, materiale

Motivo:
Nel progetto guida parliamo di Registro del laboratorio scolastico, quindi "strumento" è più vicino al linguaggio del problema.

Esercizio: rinomina senza cambiare comportamento

Scegli tre nomi confusi e rinominali.

Prima:

const list = [];

function addItem(data) {
  list.push(data);
}

Dopo:

const strumenti = [];

function registraStrumento(datiStrumento) {
  strumenti.push(datiStrumento);
}

Non hai cambiato architettura, ma hai migliorato leggibilità.

Verifica:

• il programma funziona ancora;
• le ricerche usano il nuovo nome;
• non restano variabili vecchie con nomi contraddittori.

Cosa produrre

Alla fine della lezione devi avere:

• un glossario con almeno dieci termini;
• una lista di sinonimi da evitare;
• almeno cinque nomi consigliati per file o funzioni;
• almeno tre rinomine applicate o proposte nel codice fragile;
• una scelta chiara sulla lingua usata nel progetto.

Domande di comprensione

Rispondi per iscritto:

• Perché un glossario può influenzare l’architettura?
• Qual è la differenza tra strumento e prestito?
• Perché item o manager sono nomi deboli?
• Quale parola userai per indicare la persona a cui viene assegnato uno strumento?
• Quale termine del glossario diventerà presto un caso d’uso?

Controllo finale

La lezione è completata quando puoi rispondere sì:

• ho scelto parole coerenti per il dominio;
• so distinguere strumento, prestito e segnalazione;
• ho definito gli stati principali;
• ho evitato nomi generici come manager e data;
• il glossario può guidare i prossimi moduli.

Nella prossima lezione useremo glossario e regole per scrivere requisiti verificabili.