Documenta automaticamente il tuo codice Java con Javadoc

Se esegui qualsiasi tipo di programmazione, sarai ben consapevole che uno dei compiti più noiosi coinvolti è documentare il tuo codice. Che tu lo trovi leggermente fastidioso o un'impresa che affronti con assoluto terrore, la documentazione del codice è essenziale. Altri hanno bisogno di capire come funziona il tuo codice e potresti anche essere uno di loro se lo leggerai in un secondo momento!

Java fornisce convenientemente una soluzione integrata al problema: Javadoc.

Javadoc può aiutarti a documentare il tuo codice automaticamente

Spero che tu già lo segui buone pratiche di codifica e includi commenti esplicativi nel tuo codice. Sebbene questo tipo di commento nel codice sia sicuramente utile, in realtà non fornisce nulla di paragonabile a un manuale.

Certo, un altro programmatore può esaminare il tuo codice e leggere le classi, i metodi e le funzioni specifici che si trovano di fronte a lui. Tuttavia, è estremamente difficile ottenere una buona panoramica di tutto il codice o trovare funzioni che potrebbero essere utili quando non si sa che esistono. Javadoc mira a risolvere questo problema.

Javadoc genererà automaticamente un manuale HTML dettagliato e di facile lettura per tutto il tuo codice. Soprattutto, lo fa utilizzando commenti di codice che probabilmente stai già scrivendo.

Che cos'è esattamente Javadoc e come funziona?

Javadoc è un programma autonomo che viene fornito in bundle con le versioni Java Development Kit (JDK) di Oracle. In effetti, non puoi scaricarlo separatamente. Quando scarichi e installa una delle versioni JDK di Oracle, installerà anche Javadoc.

Quando lo esegui, Javadoc genera documentazione HTML da commenti formattati in modo speciale nel codice sorgente Java. Questo processo crea una documentazione più utile e leggibile, incoraggiando anche le migliori pratiche.

In poche parole, Javadoc ti permette di scrivere il tuo codice e la sua documentazione allo stesso tempo. Semplifica il flusso di lavoro e ti consente di utilizzare il tuo tempo in modo più efficiente.

Javadoc funziona analizzando i commenti formattati in modo speciale nel codice e convertendoli in output HTML. L'unica modifica che devi davvero apportare è includere determinate stringhe nei tuoi commenti. Questi consentono a Javadoc di sapere cosa vuoi includere nella documentazione finale.

I commenti Javadoc devono precedere immediatamente una dichiarazione di classe, campo, costruttore o metodo. Il commento stesso dovrebbe:

• Inizia con i tre personaggi /**.
• Includere un asterisco all'inizio di ogni nuova riga.
• Chiudi con i due personaggi */.

All'interno dei commenti, puoi includere HTML nell'output finale e includere tag che genereranno collegamenti a parti rilevanti della tua base di codice. Puoi anche usare cose come tag immagine HTML per includere immagini nella documentazione finale. Una volta che ti sei abituato al formato e ai tag disponibili, scrivere tali commenti è un gioco da ragazzi.

Ecco un esempio per illustrare semplici commenti Javadoc che descrivono una funzione che ottiene un'immagine da un URL e la stampa sullo schermo. Il commento precede immediatamente la funzione e descrive ciò che fa. Questo blocco di commenti utilizza anche tre variabili specifiche della sezione: @param, @Restituzione, e @vedere.

/**
* Restituisce un oggetto Immagine che può quindi essere dipinto sullo schermo.
* L'argomento URL deve specificare un valore assoluto {@collegamento URL}. Il nome
* argomento è uno specificatore relativo all'argomento URL.
* 

* Questo metodo restituisce sempre immediatamente, indipendentemente dal fatto che il
* l'immagine esiste. quando questo l'applet tenta di disegnare l'immagine
* lo schermo, i dati verranno caricati. Le primitive grafiche
* che disegna l'immagine dipingerà in modo incrementale sullo schermo.
*
* @param url un URL assoluto che fornisce la posizione di base dell'immagine
* @param denominare la posizione dell'immagine, relativa all'argomento dell'URL
* @Restituzione l'immagine all'URL specificato
* @vedere Immagine
*/
pubblico Immagine getImage(URL URL, nome stringa){
Tentativo {
Restituzione getImage(nuovo URL(URL, nome));
 } presa (Eccezione URLmalformata e) {
Restituzionenullo;
 }
}

Quando Javadoc elabora il codice sopra, genera una pagina web simile alla seguente:

Un browser esegue il rendering dell'output Javadoc più o meno allo stesso modo in cui visualizza qualsiasi documento HTML. Javadoc ignora gli spazi bianchi aggiuntivi e le interruzioni di riga a meno che non utilizzi tag HTML per creare quello spazio.

I tag @ utilizzati alla fine del commento generano il file Parametri, ritorna, e Guarda anche sezioni che vedi.

Dovresti seguire il @param tag con il nome del parametro, uno spazio e una descrizione dello stesso. Nel caso sopra, ci sono due parametri: url e nome. Si noti che entrambi appaiono sotto la stessa intestazione Parametri nell'output della documentazione. È possibile elencare tutti i parametri necessari per la funzione o il metodo che si sta descrivendo.

Il @Restituzione tag documenta il valore che la funzione restituisce, se non del tutto. Può essere una semplice descrizione di una parola o molte frasi, a seconda delle circostanze.

Il @vedere tag consente di contrassegnare altre funzioni correlate o rilevanti. In questo caso, il tag @see si riferisce ad un'altra funzione chiamata semplicemente Immagine. Nota che i riferimenti fatti con questo tag sono link cliccabili, consentendo al lettore di saltare all'elemento referenziato nell'HTML finale.

Sono disponibili più tag come @version, @author, @exception e altri. Se utilizzati correttamente, i tag aiutano a mettere in relazione gli elementi tra loro e consentono di navigare facilmente nella documentazione.

Esecuzione di Javadoc sul tuo codice sorgente

Invochi Javadoc sulla riga di comando. Puoi eseguirlo su singoli file, intere directory, pacchetti java o su un elenco di singoli file. Per impostazione predefinita, Javadoc genererà i file di documentazione HTML nella directory in cui si immette il comando. Per ottenere aiuto sui comandi specifici disponibili è sufficiente inserire:

javadoc --aiuto

Per vedere esattamente cosa può fare Javadoc in modo più dettagliato, controlla la documentazione ufficiale da Oracolo. Per creare un rapido insieme di documentazione su un singolo file o directory puoi entrare javadoc sulla riga di comando seguito da un nome file o da un carattere jolly.

javadoc ~/code/nomefile.java
javadoc ~/code/*.Giava

Sopra c'è un elenco dei file e delle directory che Javadoc ha creato. Come puoi vedere, ce ne sono parecchi. Per questo motivo, dovresti essere sicuro di non trovarti nella stessa directory del tuo codice sorgente quando esegui il programma. Ciò potrebbe creare un bel pasticcio.

Per visualizzare i documenti appena creati, apri semplicemente il file indice.html file nel tuo browser preferito. Otterrai una pagina come la seguente:

Questa è la documentazione per una singola, breve classe Java per dimostrare l'output. L'intestazione mostra il nome della classe e i metodi inclusi al suo interno. Scorrendo verso il basso vengono visualizzate definizioni più dettagliate di ciascuno dei metodi di classe.

Come puoi vedere, per qualsiasi tipo di progetto Java, specialmente quelli di grandi dimensioni con molte migliaia di righe di codice, questo tipo di documentazione ha un valore inestimabile. Sarebbe una sfida conoscere una grande base di codice leggendo il suo codice sorgente. Le pagine Javadoc rendono questo processo molto più veloce e facile da seguire.

Javadoc può aiutarti a mantenere il tuo codice Java e tutta la documentazione pertinente organizzata e facile da usare. Che tu lo stia facendo per il tuo futuro smemorato o per rendere le cose più facili per una grande squadra, Javadoc è un potente strumento che può cambiare il modo in cui scrivi e interagisci con la tua codifica Java progetti.

Gli 8 migliori blog Java per programmatori

Leggi Avanti