Laboratorio de Programación  >  Material de estudio  >  Apuntes  >  Escritura de programas  >  Documentación de código

Documentación de código

José A. Mañas <jmanas@dit.upm.es>
Dept. de Ingeniería de Sistemas Telemáticos
Universidad Politécnica de Madrid
8 de mayo, 2003

1. Introducción

Documentar el código de un programa es añadir suficiente información como para explicar lo que hace, punto por punto, de forma que no sólo los ordenadores sepan qué hacer, sino que además los humanos entiendan qué están haciendo y por qué.

Porque entre lo que tiene que hacer un programa y cómo lo hace hay una distancia impresionante: todas las horas que el programador ha dedicado a pergeñar una solución y escribirla en el lenguaje que corresponda para que el ordenador la ejecute ciegamente.

Documentar un programa no es sólo un acto de buen hacer del programador por aquello de dejar la obra rematada. Es además una necesidad que sólo 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 sólo es cuestión 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 razón, 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 revisión de código 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 añadir 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:

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 líneas (que probablemente comiencen con el carácter "*") y terminan con los caracteres "*/".
una línea
Comienzan con los caracteres "//" y terminan con la línea
tipo C
Comienzan con los caracteres "/*", se pueden prolongar a lo largo de varias líneas (que probablemente comiencen con el carácter "*") y terminan con los caracteres "*/".
Cada tipo de comentario se debe adaptar a un propósito:
javadoc
Para generar documentación externa (ver comentarios javadoc más abajo)
una línea
Para documentar código que no necesitamos que aparezca en la documentación externa (que genere javadoc)

Este tipo de comentarios se usará incluso cuando el comentario ocupe varias líneas, cada una de las cuales comenzará con "//"

tipo C
Para eliminar código. Ocurre a menudo que código obsoleto no queremos que desaparezca, sino mantenerlo "por si acaso". Para que no se ejecute, se comenta.
(En inglés se suele denominar "comment out")

Javadoc, que veremos posteriormente, impone sus propias reglas prácticas.

5. ¿Cuándo hay que poner un comentario?

Por obligación (javadoc):
  1. al principio de cada clase
  2. al principio de cada método
  3. ante cada variable de clase

Por conveniencia (una línea):

  1. al principio de fragmento de código no evidente
  2. a lo largo de los bucles

Y por si acaso (una línea):

  1. siempre que hagamos algo raro
  2. siempre que el código no sea evidente

Es decir, que los comentarios más 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 refiriéndose a un algoritmo que ya no utilizamos.

6. Javadoc: documentación de APIs

El paquete de desarrollo Java incluye una herramienta, javadoc, para generar un conjunto de páginas web a partir de los ficheros de código. Esta herramienta toma en consideración algunos comentarios para generar una documentación bien presentada de clases y componentes de clases (variables y métodos).

Aunque javadoc no ayuda a la comprensión de los detalles de código, si ayuda a la comprensión de la arquitectura de la solución, lo que no es poco. Se dice que javadoc se centra en la interfaz (API - Application Programming Interface) de las clases y paquetes Java.

Javadoc realza algunos comentarios, de los que exige una sintaxis especial. Deben comenzar por "/**" y terminar por "*/", incluyendo una descripción y algunas etiquetas especiales:

  /**
   * Parte descriptiva.
   * Que puede consistir de varias frases o párrafos.
   *
   * @etiqueta texto específico de la etiqueta
   */

Estos comentarios especiales deben aparecer justo antes de la dclaración de una clase, un campo o un método en el mismo código fuente. En las siguientes secciones se detallan las etiquetas (tags) que javadoc sabe 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 explicación concisa y contundente del elemento documentado. Las demás frases entrarán en detalles.

6.1. Documentación de clases e interfaces

Deben usarse al menos las etiquetas:

La tabla muestra todas las etiquetas posibles y su interpretación:
@authornombre del autor
@versionidentificación de la versión y fecha
@seereferencia a otras clases y métodos

6.2. Documentación de constructores y métodos

Deben usarse al menos las etiquetas:

La tabla muestra todas las etiquetas posibles y su interpretación:
@paramnombre del parámetro descripción de su significado y uso
@return  descripción de lo que se devuelve
@exceptionnombre de la excepción excepciones que pueden lanzarse
@throwsnombre de la excepción excepciones que pueden lanzarse

@exception y @throws se pueden usar indistintamente.

6.3. Documentación de campos

Ninguna etiqueta es obligatoria.

6.4. Ejecución de javadoc

La mayor parte de los entornos de desarrollo incluyen un botón para llamar a javadoc así como opciones de configuración.

No obstante, siempre puede ir al directorio donde instaló en JDK y ejecutar javadoc directamente sobre el código fuente Java:

  ...> {directorio de instalación}/javadoc *.java

La herramienta javadoc admite miles de opciones. Algunas de las más usadas aparecen a continuación:

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          Recursively copy doc-file subdirectories
-splitindex               Split index into one file per letter
-windowtitle <text>       Browser window title for the documenation
-doctitle <html-code>     Include title for the overview page
-header <html-code>       Include header text for each page
-footer <html-code>       Include footer text for each page
-bottom <html-code>       Include bottom text for each page

javadoc -help despliega un catálogo completo de opciones.

7. Referencias

Sun Microsystems, empresa creadora de Java, ha dedicado extenso material a la descripción de cómo documentar las interfaces de los programas:
How to Write Doc Comments for the Javadoc Tool

Javadoc se utiliza sistemáticamente para documentar el entorno de desarrollo Java.