Material de estudio > Apuntes > Escritura de programas > Documentación de código
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:
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.
"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
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:
Este tipo de comentarios se usará incluso cuando el comentario ocupe varias líneas, cada una de las cuales comenzará con "//"
Javadoc, que veremos posteriormente, impone sus propias reglas prácticas.
Por conveniencia (una línea):
Y por si acaso (una línea):
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.
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.
La tabla muestra todas las etiquetas posibles y su interpretación:
@author | nombre del autor |
@version | identificación de la versión y fecha |
@see | referencia a otras clases y métodos |
La tabla muestra todas las etiquetas posibles y su interpretación:
@param | nombre del parámetro | descripción de su significado y uso |
@return | descripción de lo que se devuelve | |
@exception | nombre de la excepción | excepciones que pueden lanzarse |
@throws | nombre de la excepción | excepciones que pueden lanzarse |
@exception y @throws se pueden usar indistintamente.
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.
How to Write Doc Comments for the Javadoc Tool
Javadoc se utiliza sistemáticamente para documentar el entorno de desarrollo Java.