Struttura iniziale di cartelle e file

La struttura di un progetto comunica come pensi.

Se tutto è in un file solo, ogni modifica diventa una caccia al tesoro. Se invece crei troppe cartelle prima di sapere che cosa ci andrà dentro, il progetto sembra ordinato ma non lo è davvero.

In questa lezione prepariamo una struttura iniziale: piccola, avviabile e pronta a crescere.

Obiettivo della lezione

Alla fine devi avere:

• una struttura di cartelle semplice;
• file con responsabilità iniziali chiare;
• dati separati dal punto di ingresso;
• una pagina che carica il codice JavaScript;
• nomi di file comprensibili;
• nessuna cartella decorativa;
• una spiegazione breve della struttura nel README.

Questa lezione non serve a creare l’architettura finale. Serve a creare un punto di partenza leggibile.

Non partiamo dalla struttura finale

Durante il corso arriveremo a una struttura simile:

src/
  domain/
  application/
  infrastructure/
  presentation/

Ma non la creiamo subito.

Perché? Perché all’inizio avremmo cartelle vuote o quasi vuote. Una cartella vuota non insegna architettura. Una cartella con dentro codice messo a caso insegna ancora meno.

Prima vogliamo vedere il problema:

• dati e UI che iniziano a mescolarsi;
• funzioni che crescono troppo;
• regole scritte nel posto sbagliato;
• salvataggio che rischia di entrare nella logica.

Quando questi problemi saranno visibili, separare i livelli avrà senso.

Struttura consigliata

Parti così:

registro-laboratorio/
  README.md
  index.html
  src/
    main.js
    datiIniziali.js

Ogni file ha un compito:

File	Responsabilità iniziale
README.md	Spiega che cosa stai costruendo e come si avvia.
index.html	Contiene la pagina HTML minima.
src/main.js	È il punto di ingresso JavaScript dell’applicazione.
src/datiIniziali.js	Contiene gli strumenti di esempio.

Questa struttura è volutamente piccola. Il suo valore sta nel fatto che non mente: il progetto è ancora piccolo.

Perché separare subito i dati

Potresti scrivere gli strumenti direttamente in main.js.

Esempio fragile:

const strumenti = [
  { id: "str-001", nome: "Notebook Lenovo 01", stato: "disponibile" },
  { id: "str-002", nome: "Kit Arduino Base", stato: "disponibile" },
];

const app = document.querySelector("#app");
app.innerHTML = strumenti.map((strumento) => `<p>${strumento.nome}</p>`).join("");

Funziona, ma mescola già due responsabilità:

• definire i dati;
• mostrare i dati nella pagina.

Separare datiIniziali.js non è architettura avanzata. È igiene minima.

// src/datiIniziali.js
export const strumentiIniziali = [
  {
    id: "str-001",
    nome: "Notebook Lenovo 01",
    categoria: "notebook",
    stato: "disponibile",
  },
];

// src/main.js
import { strumentiIniziali } from "./datiIniziali.js";

console.log(strumentiIniziali);

Ora sai dove cambiare i dati senza toccare subito il codice che avvia la pagina.

Preparare index.html

La pagina HTML deve essere essenziale:

<!doctype html>
<html lang="it">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Registro del laboratorio</title>
  </head>
  <body>
    <h1>Registro del laboratorio scolastico</h1>
    <main id="app"></main>

    <script type="module" src="./src/main.js"></script>
  </body>
</html>

La responsabilità di index.html è piccola:

• creare la struttura base della pagina;
• offrire un punto in cui JavaScript può disegnare il contenuto;
• caricare main.js.

Non deve contenere regole di prestito. Non deve contenere dati degli strumenti. Non deve contenere logica di ricerca.

Preparare main.js

In main.js non vogliamo ancora costruire tutta la UI. Per ora basta dimostrare che il progetto parte:

import { strumentiIniziali } from "./datiIniziali.js";

const app = document.querySelector("#app");

function renderStrumenti(strumenti) {
  return `
    <ul>
      ${strumenti
        .map(
          (strumento) => `
            <li>
              <strong>${strumento.nome}</strong>
              <span>${strumento.categoria}</span>
              <span>${strumento.stato}</span>
            </li>
          `,
        )
        .join("")}
    </ul>
  `;
}

app.innerHTML = renderStrumenti(strumentiIniziali);

Questa funzione non è ancora perfetta. Va bene così. La useremo più avanti per vedere che cosa succede quando la UI cresce troppo.

Nomi chiari, non furbi

Usa nomi comprensibili:

• strumentiIniziali, non data;
• renderStrumenti, non show;
• stato, non s;
• categoria, non cat, a meno che sia una convenzione condivisa;
• datiIniziali.js, non file1.js.

I nomi sono documentazione. In un progetto didattico contano moltissimo perché aiutano a discutere il codice in classe.

Un buon nome riduce il bisogno di spiegazioni. Un cattivo nome crea nebbia.

Cosa non creare ancora

Evita per ora cartelle come:

services/
helpers/
utils/
managers/
controllers/
models/

Questi nomi spesso diventano contenitori generici. Se non sai spiegare cosa ci andrà dentro, non creare la cartella.

In particolare, evita utils come cestino. Se una funzione ha una responsabilità chiara, più avanti troverà un posto più preciso.

La domanda da fare non è:

Quante cartelle ha un progetto professionale?

La domanda utile è:

Questa cartella mi aiuta a capire dove mettere il prossimo pezzo di codice?

Quando la struttura cambierà

Nei moduli successivi la struttura diventerà più esplicita:

src/
  domain/
  application/
  infrastructure/
  presentation/

Ma ci arriveremo dopo aver visto il problema.

Prima scriveremo un programma fragile. Poi lo divideremo in livelli.

Questo è importante: l’architettura non deve sembrare una gabbia calata dall’alto. Deve sembrare una risposta a un disordine che abbiamo riconosciuto.

Attività guidata

Crea o controlla questa struttura:

registro-laboratorio/
  README.md
  index.html
  src/
    main.js
    datiIniziali.js

Poi aggiungi almeno tre strumenti in datiIniziali.js.

Ogni strumento deve avere:

• id;
• nome;
• categoria;
• stato.

Esempio:

export const strumentiIniziali = [
  {
    id: "str-001",
    nome: "Notebook Lenovo 01",
    categoria: "notebook",
    stato: "disponibile",
  },
  {
    id: "str-002",
    nome: "Kit Arduino Base",
    categoria: "elettronica",
    stato: "disponibile",
  },
  {
    id: "str-003",
    nome: "Tablet laboratorio 03",
    categoria: "tablet",
    stato: "guasto",
  },
];

Spiegazione guidata per studiare

Questa lezione va studiata come una scelta di orientamento.

Una struttura iniziale deve aiutare a trovare le cose. Non deve prevedere tutto il futuro. Se provi a progettare subito tutte le cartelle possibili, rischi di costruire una mappa di un territorio che ancora non hai esplorato.

Nel Registro del laboratorio, per ora conosciamo poche responsabilità:

• abbiamo una pagina;
• abbiamo dati iniziali;
• abbiamo un punto di ingresso JavaScript;
• abbiamo un README.

Quindi la struttura deve rappresentare queste responsabilità, non altre.

Il criterio è questo:

ogni file deve avere un motivo chiaro per esistere

Se non sai spiegare il motivo di un file o di una cartella, probabilmente è troppo presto per crearla.

Esempio di ragionamento

Prendi questa domanda:

Dove aggiungo un nuovo strumento di esempio?

Con la struttura consigliata la risposta è semplice:

src/datiIniziali.js

Prendi un’altra domanda:

Dove cambio il modo in cui la lista viene mostrata?

Per ora la risposta è:

src/main.js

Più avanti questa risposta cambierà, perché separeremo meglio la Presentation. Ma oggi è sufficiente.

Una struttura buona per questa fase non è quella definitiva. È quella che rende chiaro il prossimo passo.

Micro-sfida

Aggiungi un quarto strumento realistico, ma scegli uno stato diverso da disponibile.

Poi rispondi:

• dove hai scritto il dato?
• dove lo hai mostrato?
• hai dovuto cambiare anche HTML?
• se domani aggiungi altri 20 strumenti, quale file crescerà?
• se domani aggiungi un filtro di ricerca, quale file rischia di crescere troppo?

Queste domande iniziano ad allenare lo sguardo architetturale.

Prodotto da consegnare

Alla fine della lezione devi mostrare:

• la struttura della cartella progetto;
• index.html che carica src/main.js;
• src/datiIniziali.js con almeno tre strumenti;
• src/main.js che importa e mostra gli strumenti;
• una breve nota nel README che descrive i file principali.

Esempio di nota:

## Struttura iniziale

- `index.html`: pagina minima del Registro.
- `src/main.js`: punto di ingresso JavaScript.
- `src/datiIniziali.js`: strumenti di esempio usati all'avvio.

Domande di comprensione

Rispondi per iscritto:

• Perché non creiamo subito domain, application, infrastructure e presentation?
• Perché separare i dati iniziali da main.js è già utile?
• Quale problema nasce se usiamo una cartella utils per tutto?
• Che cosa rende un nome di file comprensibile?
• Quando sarà il momento giusto per cambiare struttura?

Controllo finale

La lezione è completata quando puoi dire sì a queste domande:

• la cartella del progetto esiste;
• index.html carica src/main.js come modulo;
• i dati iniziali sono in un file separato;
• la pagina mostra gli strumenti;
• i nomi dei file sono comprensibili;
• non hai creato cartelle inutili;
• sai spiegare perché questa non è ancora la struttura finale.

Nel prossimo passo scriveremo un README iniziale più utile. Non sarà un documento decorativo: dovrà aiutare davvero chi apre il progetto.