1.

Introduccin
Documentar el cdigo de un programa es aadir suficiente informacin como para explicar lo que hace, punto por
punto, de forma que no slo los ordenadores sepan qu hacer, sino que adems los humanos entiendan qu estn
haciendo y por qu.
Porque entre lo que tiene que hacer un programa y cmo lo hace hay una distancia impresionante: todas las horas que
el programador ha dedicado a pergear una solucin y escribirla en el lenguaje que corresponda para que el ordenador
la ejecute ciegamente.
Documentar un programa no es slo un acto de buen hacer del programador por aquello de dejar la obra rematada. Es
adems una necesidad que slo se aprecia en su debida magnitud cuando hay errores que reparar o hay que extender el
programa con nuevas capacidades o adaptarlo a un nuevo escenario. Hay dos reglas que no se deben olvidar nunca:
1. todos los programas tienen errores y descubrirlos slo es cuestin de tiempo y de que el programa tenga
xito y se utilice frecuentemente
2. todos los programas sufren modificaciones a lo largo de su vida, al menos todos aquellos que tienen xito
Por una u otra razn, todo programa que tenga xito ser modificado en el futuro, bien por el programador original,
bien por otro programador que le sustituya. Pensando en esta revisin de cdigo es por lo que es importante que el
programa se entienda: para poder repararlo y modificarlo.

2. Citas
"If your program isn't worth documenting, it probably isn't worth running"
J. Nagler. 1995
Coding Style and Good Computing Practices

"do not document bad code - rewrite it"

R. Caron. 2000
Coding Techniques and Programming Practices

"Write the documentation before you write the code."

S.W. Ambler. 2000.
Writing Robust Java Code

3. Qu hay que documentar?

Hay que aadir explicaciones a todo lo que no es evidente.
No hay que repetir lo que se hace, sino explicar por qu se hace.

Y eso se traduce en:

de qu se encarga una clase? un paquete?
qu hace un mtodo?
cul es el uso esperado de un mtodo?
para qu se usa una variable?
cul es el uso esperado de una variable?
qu algoritmo estamos usando? de dnde lo hemos sacado?
qu limitaciones tiene el algoritmo? ... la implementacin?
qu se debera mejorar ... si hubiera tiempo?

4. Tipos de comentarios
En Java disponemos de tres notaciones para introducir comentarios:

javadoc
Comienzan con los caracteres "/**", se pueden prolongar a lo largo de varias lneas (que probablemente
comiencen con el carcter "*") y terminan con los caracteres "*/".
una lnea
Comienzan con los caracteres "//" y terminan con la lnea
tipo C
 Comienzan con los caracteres "/*", se pueden prolongar a lo largo de varias lneas (que probablemente comiencen
con el carcter "*") y terminan con los caracteres "*/".

Cada tipo de comentario se debe adaptar a un propsito:

javadoc
Para generar documentacin externa (ver comentarios javadoc ms abajo)
una lnea
Para documentar cdigo que no necesitamos que aparezca en la documentacin externa (que genere javadoc)
Este tipo de comentarios se usar incluso cuando el comentario ocupe varias lneas, cada una de las cuales
comenzar con "//"
tipo C
Para eliminar cdigo. Ocurre a menudo que cdigo obsoleto no queremos que desaparezca, sino mantenerlo "por si
acaso". Para que no se ejecute, se comenta.
(En ingls se suele denominar"comment out")

Javadoc, que veremos posteriormente, impone sus propias reglas prcticas.

5. Cundo hay que poner un comentario?

Por obligacin (javadoc):
1. al principio de cada clase
2. al principio de cada mtodo
3. ante cada variable de clase
Por conveniencia (una lnea):
4. al principio de fragmento de cdigo no evidente
5. a lo largo de los bucles
Y por si acaso (una lnea):
6. siempre que hagamos algo raro
7. siempre que el cdigo no sea evidente
Es decir, que los comentarios ms vale que sobren que que falten.
Y una nota de cautela, cuando un programa se modifica, los comentarios deben modificarse al tiempo, no sea que los
comentarios acaben refirindose a un algoritmo que ya no utilizamos.

6. Javadoc: documentacin de APIs

El paquete de desarrollo Java incluye una herramienta,javadoc, para generar un conjunto de pginas web a partir de
los ficheros de cdigo. Esta herramienta toma en consideracin algunos comentarios para generar una documentacin
bien presentada de clases y componentes de clases (variables y mtodos).
Aunquejavadocno ayuda a la comprensin de los detalles de cdigo, si ayuda a la comprensin de la arquitectura de la
solucin, lo que no es poco. Se dice quejavadocse centra en la interfaz(API - Application Programming Interface)de
las clases y paquetes Java.
Javadocrealza algunos comentarios, de los que exige una sintaxis especial. Deben comenzar por"/**"y terminar
por"*/", incluyendo una descripcin y algunas etiquetas especiales:

/**
* Parte descriptiva.
* Que puede consistir de varias frases o prrafos.
*
* @etiqueta texto especfico de la etiqueta
*/

Estos comentarios especiales deben aparecer justo antes de la dclaracin de una clase, un campo o un mtodo en el
mismo cdigo fuente. En las siguientes secciones se detallan las etiquetas (tags) quejavadocsabe interpretar en cada
uno de los casos.
Como regla general, hay que destacar que la primera frase (el texto hasta el primer punto) recibir un tratamiento
detacado, por lo que debe aportar una explicacin concisa y contundente del elemento documentado. Las dems frases
entrarn en detalles.

6.1. Documentacin de clases e interfaces

Deben usarse al menos las etiquetas:

@author
@version
La tabla muestra todas las etiquetas posibles y su interpretacin:
@author nombre del autor
@version identificacin de la versin y fecha
@see referencia a otras clases y mtodos

6.2. Documentacin de constructores y mtodos

Deben usarse al menos las etiquetas:

@param
una por argumento de entrada
@return
si el mtodo no esvoid
@exception @throws
una por tipo deExceptionque se puede lanzar
(@exception y @throws se pueden usar indistintamente).
La tabla muestra todas las etiquetas posibles y su interpretacin:
@param nombre del parmetro descripcin de su significado y uso
@return descripcin de lo que se devuelve
@exception nombre de la excepcin excepciones que pueden lanzarse
@throws nombre de la excepcin excepciones que pueden lanzarse

@exception y @throws se pueden usar indistintamente.

6.3. Documentacin de campos

Ninguna etiqueta es obligatoria.

6.4. Ejecucin de javadoc

La mayor parte de los entornos de desarrollo incluyen un botn para llamar ajavadocas como opciones de
configuracin.
No obstante, siempre puede ir al directorio donde instal en JDK y ejecutarjavadocdirectamente sobre el cdigo
fuente Java:

...> {directorio de instalacin}/javadoc *.java

La herramientajavadocadmite miles de opciones. Algunas de las ms usadas aparecen a continuacin:

usage: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files]

-public Show only public classes and members
-protected Show protected/public classes and members (default)
-package Show package/protected/public classes and members
-private Show all classes and members
-sourcepath <pathlist> Specify where to find source files
-classpath <pathlist> Specify where to find user class files
-verbose Output messages about what Javadoc is doing

-d <directory> Destination directory for output files

-version Include @version paragraphs
-author Include @author paragraphs
 -docfilessubdirs
-splitindex
-windowtitle <text>
-doctitle <html-code>
-header <html-code>
-footer <html-code>
-bottom <html-code>
Recursively copy doc-file subdirectories
Split index into one file per letter
Browser window title for the documenation
Include title for the overview page
Include header text for each page
Include footer text for each page
Include bottom text for each page

javadoc -helpdespliega un catlogo completo de opciones.

7. Referencias
Sun Microsystems, empresa creadora de Java, ha dedicado extenso material a la descripcin de cmo documentar las
interfaces de los programas:

How to Write Doc Comments for the Javadoc Tool

Javadocse utiliza sistemticamente para documentarel entorno de desarrollo Java.