Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Documentazione Automatica

Lezione 8 di 20 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Documentare senza Interrompere lo Sviluppo
  2. Documentazione Inline: JSDoc e Commenti
  3. Generare un README
  4. Documentazione delle API
  5. Documentazione dell’Architettura
  6. Aggiornare la Documentazione Esistente
  7. Automatizzare tramite AGENTS.md
  8. Punti chiave

Documentare senza Interrompere lo Sviluppo

Tutti concordano sul fatto che la documentazione sia necessaria, eppure quasi nessuno la scrive. Perché? Perché la stesura avviene nel momento peggiore: la funzionalità è terminata e l’attenzione si è già spostata altrove. Codex sposta questo costo. Analizza il codice così com’è e produce una documentazione completa e aggiornata, allineata all’implementazione reale. Questa fedeltà è il fattore decisivo: una documentazione inventata fa più danni di una pagina bianca, perché ispira una falsa sicurezza.

Documentazione Inline: JSDoc e Commenti

La documentazione più consultata appare direttamente nel tooltip dell’editor, esattamente dove sorge il dubbio.

"Add JSDoc documentation to all exported functions 
and types in src/lib/. Include a description, 
parameters, return type, and a usage example 
for each function."

Ecco cosa produce Codex per una funzione di calcolo del prezzo:

/**
 * Calculates the total price after applying the discount.
 * 
 * @param basePrice - Unit price in cents
 * @param quantity - Number of units (minimum 1)
 * @param discountPercent - Discount percentage (0-100)
 * @returns The total price in cents, rounded to an integer
 * 
 * @example
 * calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
 * 
 * @throws {ValidationError} If price or quantity is negative
 */
export function calculateTotal(
  basePrice: number,
  quantity: number,
  discountPercent: number = 0
): number {
  // ...
}

Due informazioni qui valgono più di tutto il resto: l’unità di misura (centesimi, non euro) e l’eccezione lanciata per valori negativi. Queste sono esattamente le due cose che uno sviluppatore scopre solitamente in produzione, dopo aver fatturato ai clienti dieci volte meno del previsto. Codex le ha estratte dall’implementazione, non da un modello di commento generico.

Generare un README

Per un nuovo progetto, o per un README diventato fittizio a causa della deriva del codice, elenca ciò che il lettore deve essere in grado di fare una volta terminata la lettura.

"Generate a comprehensive README.md for this project. Include:
- Project description and purpose
- Prerequisites (Node.js, PostgreSQL, etc.)
- Step-by-step installation instructions
- Required environment variables (without values)
- Available commands (dev, test, build, lint)
- Project structure
- How to contribute"

Codex si basa su package.json, sui file di configurazione e sull’albero delle directory reale per produrre un documento che rifletta lo stato attuale del progetto. L’istruzione “without values” (senza valori) non è un capriccio: senza di essa, un agente che ha appena letto un .env.example ben popolato potrebbe copiare allegramente valori che non vuoi vedere in un file versionato.

Documentazione delle API

Per un’API REST, la documentazione più economica è quella che altri strumenti possono consumare senza intervento umano.

"Analyze all routes in src/api/routes/ and generate 
an openapi.yaml file. Include request and response 
schemas based on existing TypeScript types and 
Zod validations."

Tutto viene estratto dal codice: percorsi delle route, metodi HTTP, schemi di validazione e tipi di risposta. La specifica risultante è quindi fedele all’implementazione, permettendo ai tuoi consumatori di derivare un client tipizzato o una collezione di test senza farti una singola domanda.

Documentazione dell’Architettura

Le decisioni architetturali vengono raramente messe per iscritto. Quando accade, descrivono l’intento iniziale piuttosto che la realtà tre anni dopo. Chiedi a Codex di formalizzare ciò che esiste effettivamente nel codice.

"Analyze the project architecture and create a 
docs/architecture.md file documenting:
- Layers (API, services, repositories, models)
- Data flow for a typical request
- Patterns used (repository pattern, dependency injection)
- Dependencies between modules"

Questo documento ha un beneficio secondario inaspettato: descrivendo le dipendenze tra i moduli così come sono realmente, espone accoppiamenti che nessuno aveva riconosciuto, come il servizio di fatturazione che importa una utility dal modulo di autenticazione.

Aggiornare la Documentazione Esistente

Una documentazione obsoleta è peggio di nessuna documentazione, perché fa perdere tempo con autorità.

"Compare README.md with the current state of the project. 
Identify outdated sections (commands that no longer exist, 
removed dependencies, incorrect instructions). 
Update the README accordingly."

Codex confronta ogni affermazione nel README con il codice effettivo e corregge le incongruenze. Programma questo compito periodicamente, ad esempio prima di ogni release, invece di scoprire la sua necessità il giorno in cui un nuovo assunto scopre che nessuno dei comandi di installazione funziona.

Automatizzare tramite AGENTS.md

Per smettere di trattare la documentazione come un compito separato, rendila un vincolo permanente del progetto.

## Documentation
- Every new exported function MUST have complete JSDoc
- API changes MUST update openapi.yaml
- Comment format: French for business logic, English for technical details

Con queste tre regole, ogni attività di sviluppo include il proprio aggiornamento della documentazione. Il divario tra codice e descrizione smette di allargarsi silenziosamente, che è l’unico modo sostenibile per vincere questa battaglia.

Punti chiave

  • Codex genera documentazione fedele al codice reale, non inventata
  • La documentazione inline (JSDoc) è la più utile per il lavoro quotidiano
  • Codex può produrre README, specifiche OpenAPI e documentazione architetturale
  • Usa Codex per rilevare e correggere la documentazione obsoleta
  • Aggiungi regole di documentazione ad AGENTS.md per automatizzare il processo