Ci sono molte informazioni che potrebbero essere considerate "documentazione". Ecco il mio riassunto, con alcune best practice per ciascuna:

1. Class, metodo, funzione e nomi di variabili. Questo è fondamentale per avere un codice leggibile. Tutta l'altra documentazione può facilmente non essere aggiornata, ma il testo che il compilatore in realtà compila quasi per definizione non può. È il riferimento finale a ciò che fa il software, e una buona denominazione dovrebbe essere una priorità qui.

2. Commenti in linea. All'interno di funzioni e metodi, avere buoni commenti per separare sezioni funzionali e spiegare algoritmi complicati sono preziosi. Assicurati che non siano scaduti.

3. Commenti in stile JavaDoc. Questi sono ottimi per generare pagine Web per una facile lettura di una base di codice stabile, ma possono avere un valore limitato con il codice in fase di sviluppo attivo. Sono meglio creati ed elaborati dopo che il codice si è stabilizzato, in particolare per il codice che viene utilizzato a livello di sistema. Sono meno preziosi per il codice utilizzato in un solo posto.

4. Documentazione per gli sviluppatori. Questo include le guide per iniziare a sviluppare il software (pacchetti da installare, compilare procedure, suggerimenti per il debug, stili di codifica, ecc.). Ciò è utile quando si avvia per la prima volta un progetto (o si torna ad esso dopo un'assenza), ma viene usato raramente in altri momenti. In un pizzico, questa informazione può essere ottenuta da altri membri del team.

5. Documentazione utente / amministratore / operatore. Include informazioni su come installare, amministrare e utilizzare il software. I clienti apprezzano questo quando hanno problemi, quindi dovrebbe essere buono. Idealmente, il software dovrebbe essere auto-esplicativo, ma a volte ciò non è possibile o appropriato. Questo dovrebbe essere scritto da qualcuno con buone capacità di scrittura.

Tutti questi tipi di documentazione contribuiscono al valore del software, ma dei cinque gruppi, direi che 1 e 5 sono i più importanti e 3 è il meno importante. Sfortunatamente, ad eccezione di 3, non conosco alcun software (oltre agli editor di testo) per facilitare la generazione della documentazione in questione. Ci sono molti buoni libri sulla documentazione e sulla scrittura di codice di alta qualità in generale. Uno dei miei preferiti è codice completo .

La documentazione di JavaDoc può essere più o meno dettagliata. Ad esempio, la documentazione inline (in .NET, simile a JavaDoc) è piuttosto dettagliata su uno dei progetti che sto lavorando su , contenente non solo la descrizione di un metodo, ma anche l'elenco delle possibili eccezioni, gli esempi che mostrano come utilizzare un metodo (con codice sorgente demo nei commenti), ecc.

Avere una documentazione in linea persino dettagliata è una buona cosa, ma non dimenticare che:

1. Molte cose non possono essere descritte nel codice sorgente (e nella documentazione nei file del codice sorgente). Che dire:

   • Problemi di sicurezza?
   • Istruzioni su come distribuire il progetto?
   • Dettagli sull'ambiente?
   • Linee guida di stile?
   • ecc.

2. Una buona documentazione incorporata è una buona cosa, ma non è una scusa per evitare di scrivere un codice buono e leggibile. In particolare, pensa a modi in cui il codice può essere migliorato per evitare una documentazione esplicita. Ad esempio, .NET ha contratti di codice che aumentano la chiarezza del codice, garantendo nel contempo che i contratti non saranno mai (o raramente) obsoleti.

Perché?

La migliore documentazione è un codice scritto in modo chiaro con uno scopo e un processo ovvi. I commenti per spiegare ciò che viene fatto sono quindi superflui. I commenti per spiegare perché il codice esiste sono utili, se non ovvi dal contesto.

La domanda di fondo è: qual è lo scopo della documentazione che hai in mente?

La documentazione fine a se stessa può essere uno spreco di energie.