Tutorial 05 - Comentarios en el código fuente

  Este tutorial introduce al lector en los diferentes tipos de comentarios en el código fuente Java, y en las buenas prácticas de su uso.


1. Acerca de los comentarios
  Un comentario en un archivo de código fuente es una secuencia de caracteres que no será tenida en cuenta por el compilador.
  Aunque su uso, por ese motivo, puede parecer innecesario, los comentarios bien dispuestos en el código son de mucha utilidad.
  Debido al volumen del código fuente en los sistemas que se desarrollan actualmente, es habitual que un programador necesite utilizar, revisar o modificar el código que escribió otro programador.
  Los comentarios concisos en el lugar correcto, facilitan estas tareas a los programadores. Así como los comentarios abultados y mal redactados, perturban la tarea.
  Por ejemplo, si se necesita utilizar una variable y se identifica con el nombre "contador"; agregar un comentario que diga "Este es un contador.", no aporta ningún dato útil al que lea el código.
  En cambio, si se utiliza una variable llamada "loop", y se la comenta con "Número de iteraciones en dimensión h de la matriz.", seguramente aporte información valiosa en un código que utilice varios bucles anidados.
  En Java, también se prefieren los nombres identificadores autocomentados cuando sea posible. Esto es, la utilización de nombres que sean descriptivos de la función que cumple el elemento identificado, sea una variable, un método, etc, evitando así, la necesidad de comentarios.

2. Tipos de comentarios
  El compilador Java admite tres tipos de comentarios:
  - Comentarios de línea simple: El compilador ignorará todo lo escrito desde la aparición de los caracteres "//" (dos barras), hasta el fin de la misma línea.

// Actualización de base de datos.

  - Comentarios multilínea: El compilador pasa por alto todo lo que está entre los caracteres "/*" (barra y asterisco) y "*/" (asterisco y barra).

/* Implementación por defecto del algoritmo de busquedaque toma los elementos de una cola bloqueante. */

  - Comentarios de documentación: Este es un tipo especial de comentario multilínea que es utilizado por la herramienta "javadoc", para generar la documentación del código. Esta herramienta está incluída en el directorio "bin" de la instalación del JDK. Los comentarios de documentación comienzan con los caracteres "/**" (barra y dos asteriscos) y terminan con "*/" (asterisco y barra).

3. Herramienta de documentación
  Cuando se desarrolla una aplicación, es una muy buena idea, documentarla.
  JavaDoc utiliza los comentarios de documentación del código fuente para generar archivos HTML, permitiendo al programador mantener al día la documentación.
  Si se utilizan las etiquetas provistas, esta herramienta genera la documentación en forma coherente y perfectamente ordenada. Además, si la documentación generada es incluída en el proyecto, los IDEs como Eclipse y NetBeans, brindan ayuda al programador, muy útil en el momento de escribir el código fuente.
  Las etiquetas disponibles son:
- @autor: Indica el autor de una clase. Esta etiqueta puede repetirse si existe mas de un responsable.
- @deprecated: Muestra un comentario de que el elemento no debe utilizarse, aunque esté incluído. Por ejemplo, cuando un método es remplazado en el código fuente, por otro método que realiza la misma operación pero en una forma mejorada, el primer método muchas veces debe permanecer en el código por compatibilidad con otras aplicaciones. En este caso, el primer método debe marcarse como @deprecated para que todo aquel que vea la documentación evite utilizarlo debido a que es obsoleto.
- @exception: Es seguida por el nombre de la clase excepción y una descripción. Indica las situaciones en las que un método puede lanzar una excepción.
- {@link }: Inserta un enlace autocontenido a otro lugar de la documentación.
- @param: Agrega el nombre y la descripción de un parámetro de método.
- @return: Descripción del elemento devuelto por un método.
- @see: Referencia a una sección de la documentación.
- @since: Muestra desde que versión está disponible el elemento.
- @serial: Es utilizada con campos serializables.
- @serialField: Esta etiqueta debe ser utilizada en cada campo ObjectStreamField. (Fuera del alcance de este tutorial.)
- @serialData: Describe los datos escritos por el método writeObject() y Externalizable.writeExternal().
- @throws: Se utiliza en la misma forma que la etiqueta @exception.
- @version: Agrega la versión a la documentación de la clase.

3. Generación de la documentación
  En NetBeans, por cada elemento que se genera automaticamente, por ejemplo cuando se crea un proyecto, por defecto, se inserta una plantilla (template, en inglés) de código de documentación que debe ser completada por el programador.
  Esas plantillas pueden verse y modificarse seleccionando en la barra de menús, "Tools -> Templates". En la ventana que se abre, "Template Manager", dentro de la carpeta "Java" de la lista de "Templates", pueden seleccionarse las plantillas para cada elemento de código fuente en Java:

  Para los elementos de código que crea el programador, sitúandose con el cursor en la línea anterior, escribiendo "/**" (barra y dos asteriscos), al presionar la tecla "Enter" se inserta la plantilla de comentario de documentación correspondiente al elemento.
  Como se mencionó anteriormente, las plantillas de documentación deben ser completadas por el programador.
  A continuación se muestran los comentarios generados automáticamente por NetBeans y otros agregados manualmente, en el código fuente de un nuevo proyecto ("Comentarios"):

  Para generar la documentación, con el proyecto seleccionado en la solapa "Projects" de NetBeans, se debe seleccionar "Generate Javadoc" del menú "Run".
  NetBeans guarda la documentación en el directorio "dist" dentro del proyecto, dentro del directorio "javadoc":

  Además, abre un navegador mostrando la documentación generada:

  Esta documentación debe ser incluida cuando se distribuya la aplicación.

  El proyecto NetBeans con la documentación puede ser descargado desde ComentariosNetBeans.zip.

  En Eclipse, los comentarios de documentación no se incluyen por defecto en los elementos generados automáticamente. Para cambiar este comportamiento, se deben cambiar la preferencias en la barra de menús, seleccionando "Window -> Preferences"; en la ventana "Preferences", en el panel izquierdo se debe seleccionar "Java -> Code Style -> Code Templates", y allí tildar la opción "Automatically add comments for new methods and types".

  Desde la misma ventana se pueden modificar las plantillas de comentarios para personalizarlas.
  Igual que en NetBeans, para generar la plantilla de comentarios de documentación para los elementos agregados al código fuente manualmente, se debe introducir "/**" (barra y dos asteriscos) en la línea anterior al elemento, y presionar la tecla "Enter".
  Luego de completados los comentarios por parte del programador:

se puede generar la documentación, seleccionando desde la barra de menús "Project -> Generate Javadoc..." con el proyecto seleccionado en el "Project Explorer" de Eclipse. En el asistente "Generate Javadoc", todas las opciones pueden dejarse en su valor por defecto, para esta demostración. En ese caso, la documentación será generada en el directorio "doc" dentro del proyecto, cuando se haga click en el botón "Finish" del asistente.
  En la siguiente figura se puede ver la documentación generada en el directorio "doc" en el "Project Explorer" de Eclipse:

  En caso de Eclipse, esta es la documentación que debe ser incluída con el proyecto.

  Este proyecto Eclipse con su documentación puede descargarse desde Comentarios.zip.