Per a ser un programador competent s'han d'educar algunes virtuts i adquirir alguns bons costums de programació. L'elaboració d'una bona documentació de tot el codi que escrius és un d'aquests bons costums.

Pensa que el teu codi pot acabar, en moltes ocasions, en mans d'un altre programador. Si no has documentat les classes, la persona que rebi el programa haurà de llegir i interpretar tot el codi de l'aplicació. Si has documentat bé el projecte, pràcticament només s'haurà de llegir les anotacions que has fet i no el propi codi.

També et pot passar que hagis de treballar amb programes que has fet tu però els vas escriure fa mesos o, fins i tot, anys. Segur que descobriràs, amb ràbia, que tot el que estava clar quan vares fer el programa ha deixat d'estar-ho en reprendre'l. Si no vas documentar bé el projecte inicialment, ara t'hauràs de legir el codi línia a línia.

Afortunadament, Java ens posa força fàcil la documentació dels nostres projectes gràcies a l'eina javadoc, present a totes les distribucions del kit de Java. Podràs accedir a aquesta eina a través de l'IDE , que et facilita la generació de la documentació de tot un projecte amb un sol clic.

Si poses les marques adequades al codi font del teu projecte, javadoc et crearà un conjunt ordenat de pàgines web amb informació de totes i cadascuna de les classes que has escrit.

Què es pot documentar d'una classe?

Un munt de coses. Possiblement més de les que necessitaràs en un projecte ordinari. Aquestes són algunes de les possibilitats generals:

• Numerar les versions
• Informar sobre l'autor de programa
• Donar detalls sobre les característiques de la classe

A més, per a cadascun dels constructors i mètodes de la classe pots donar informació estructurada: nom del mètode, tipus de retorn, tipus i utilitat dels paràmetres, etc.

Perquè et facis una idea de com queda una classe ben documentada, visita la documentació generada amb javadoc per a la classe String en el lloc de Java Sun:    http://java.sun.com/j2se/1.4.2/docs/api/java/lang/String.html (amb el benentès que aquesta referència és per a la versió 1.4.2_05 de Java.)

Més modestament, ara documentarem el nostre darrer projecte GasHash i en generarem els fitxers de documentació.

Abans de fer-ho, et deixem un petit catecisme de la bona documentació de programes Java:

Encara que et pesi i et sembli perdre el temps, si vols donar longevitat als teus programes has de documentar sempre:

• Les feines que fa una classe o un paquet.
• Les feines que fan tots els mètodes. Per a què serveix el mètode?
• Per a què serveixen totes les variables
• Com pots millorar el mètode, cas que algun dia t'hi puguis tornar a posar.

Això significa que has de posar etiquetes javadoc

• Al principi de cada classe
• Davant de cada camp
• Davant de cada constructor
• Davant de cada mètode

I que has de fer comentaris no-javadoc, d'una sola línia o més

• Quan un fragment de codi no queda gaire clar o preveus que serà difícil d'interpretar si no dones pistes.
• Quan escrius bucles, si pot ser, en cada un dels seus passos.

Reflexiona, finalment, sobre aquests aforismes dels gurús de Java:

"If your program isn't worth documenting, it probably isn't worth running"

"Write the documentation before you write the code"

"Provide comments that augment, not repeat, program code"

"Document why something is being done, not just what"

import java.util.Collection;
import java.util.HashMap;
import java.util.Iterator;

/*
* Creat el 10-mar-2004
*
*/

/**
 * GasHash és una classe de demostració de les possibilitats
 * dels objectes <strong>HashMap</strong>.
 * El principal avantatge dels <strong>HashMap</strong>
 * respecte els ArrayList és la seva capacitat de  
 * localització individual d'un element de la llista.
 * La classe GasHash ens permet fer les següents operacions
 * sobre un suposat inventari d'una botiga de motos.
 *
 * <ul>
 * <li> Afegir motos a l'inventari
 * <li> Eliminar motos de l'inventari
 * <li> Obtenir motos de l'inventari a partir de la seva clau
 * <li> Llistar totes les motos de l'inventari
 * <li> Obtenir el número de motos de l'inventari
 * </ul>
 *
 *
 * @author Angel Solans
 * @version 10-mar-2004
 *
 */
public class GasHash {
    // En principi, els camps privats no cal comentar-los
    // a javadoc
    // Barra que serveix per a decorar la impressió
    // de l'inventari
    private static String
         BARRA = "-----------------------------";
    // El nucli del programa, l'objecte HashMap que
    // conté l'inventari
    private HashMap inventari;


    /**
     * El constructor només inicialitza l'inventari.
     * No donem cap valor a l'inventari per defecte. Després
     * d'instanciar un objecte GasHash s'ha d'anar omplint a
     * través del mètode afegeixMoto()
     */
    public GasHash() {
        inventari = new HashMap();
    }

    /**
     * Afegeix motos a la taula HashMap de l'inventari.
     * Per a la clau es recomanen valors com "honda01" o
     * "harley". Són cadenes de text totes en minúscula i
     * sense caràcters estranys ni accents. Això és així per
     * a facilitar la recerca de motos a l'inventari.
     * Al camp model es pot utilitzar qualsevol tipus de
     * caràcter perquè és la informació que apareix en els
     * llistats. Per exemple "Model X. 1100 cc. "
     * @param clau. Camp index de la taula d'inventari.
     * @param model. Camp descripció del model.
     */
    public void afegeixMoto(String clau, String model) {
        inventari.put(clau,model);
    }

    /**
     * Comptador de motos a l'inventari
     * @return el número de motos que hi ha a la botiga.
     */
    public int numeroMotos() {
        return inventari.size();
    }

    /**
     * Elimina una moto de l'inventari. Si no existeix,
     * no fa res.
     * @param clau. La clau índex de la moto.
     */
    public void eliminaMoto(String clau) {
        inventari.remove(clau);
    }

    /**
     * Retorna la descripció d'una moto a partir de la seva
     * clau. Si la clau no està a la taula, retorna un null.
     * @param la clau de la moto
     * @return la descripció de la moto
     */
    public String getMoto(String clau) {
       return (String)inventari.get(clau);
    }

    /**
     * Imprimeix la llista completa de motos de l'inventari.
     * El mètode utilitza un iterador per a recórrer
     * seqüencialment la llista. Com els HashMap no poden
     * donar directament els seus valors a un iterador, creem
     * una colecció amb els valors de l'inventari i li passem
     * a l'iterador els valors de la colecció
     */
    public void llistaMotos() {
        Collection valors = inventari.values();
        Iterator iterador = valors.iterator();
        System.out.println(BARRA);
        System.out.println("Inventari de GAS / GAS Motor");
        System.out.println(BARRA);
        while (iterador.hasNext()) {
            System.out.println(BARRA);
            System.out.println(iterador.next());
        }
    }
}

Com pots veure, hem afegit a la classe els tres tipus de comentari:

• Comentaris javadoc. Són comentaris que el generador de documentació passarà a la pàgina web de documentació de la classe. Comencen amb /** i acaben amb */. Per exemple:

    /**
     * Elimina una moto de l'inventari.
     * Si no existeix, no fa res.
     * @param clau. La clau índex de la moto.
     */

• Comentaris no javadoc multilínia. Són comentaris de més d'una línia que no passaran a la pàgina web de documentació. Pots utilitzar-los quan hagis de fer un comentari llarg intern al codi o quan vulguis que algun fragment de codi no es compil·li. Tot el que comenci per /* i acabi amb */ no es compil·larà ni passarà a la documentació de la classe. Per exemple:

    /*
     * Creat el 10-mar-2004
     *
     */

• Comentaris no javadoc d'una línia. Qualsevol fragment de codi que comença per // és ignorat pel compil·lador fins arribar al final de la línia. Serveix per a fer comentaris breus en el flux del codi que tampoc no han de passar a la documentació de la classe.

Observa que el text dels comentaris és codi HTML; ja has vist que la documentació oficial de Java es presenta en pàgines web. Per tant, si coneixes els <senyals> del codi HTML pots enriquir la presentació de les explicacions tant com vulguis. Per exemple

 * El principal avantatge dels <strong>HashMap</strong> respecte els

per a posar text en negreta o

 * <ul>
 * <li> Afegir motos a l'inventari
 * <li> Eliminar motos de l'inventari

per a crear una llista no numerada.

Hem utilitzat diferents etiquetes que comencen per @. Per exemple @author o @version. Aquestes etiquetes són marcadors especials que indiquen a javadoc que el text que ve a continuació ha de ser tractat d'una manera especial.

Quan estiguis satisfet de l'aspecte de la teva classe completament documentada, obre el menú eines del i tria l'opció Documentació del Projecte.

Quan demanis la generació de documentació, el arrancarà el programa javadoc de la teva distribució de Java, qui et crearà les pàgines de documentació del projecte motos. Sense fer res més t'obrirà el navegador i te'n presentarà la documentació. Físicament, les pàgines web estaran enregistrades en una carpeta amb el nom doc a l'interior de la carpeta del projecte motos.

Des del navegador estant, observa la pàgina que s'ha obert. A la columna de l'esquerra tens la llista de classes del projecte i, a la dreta, la documentació de la classe activa.

Pica sobre l'enllaç GasHash i observa com t'ha quedat la seva documentació:

Compara-la amb la classe GasGas, que no està documentada. Observa com l'esforç de documentar ha clarificat enormement la utilitat i la forma de treballar de la classe.

Fixa't, especialment, en el tractament que javadoc ha fet de les etiquetes @version, @author a la capçalera o @return en els mètodes.

En la documentació general d'una classe has d'intentar utilitzar sempre aquestes dues etiquetes:

• @author
• @version

que indiquen el nom de l'autor i la versió del programa. També pots afegir aquestes:

Has d'intentar ser estricte amb la documentació de mètodes i constructors, tant si té paràmetres d'entrada, valors de sortida o genera excepcions.

Segons el cas, utilitza obligatòriament les següents etiquetes:

• @param: una etiqueta per a cada argument d'entrada del mètode.
• @return: descripció de l'objecte que retorna el mètode.
• @exception: posa una etiqueta per a cada tipus d'excepció diferent que el mètode pot llençar.

A més a més, també pots utilitzar: