Como escribir comentarios para la documentación con el Javadoc

How to Write Doc Comments for the Javadoc Tool

Este es un tutorial de la convenciones usadas para la creación de comentarios en los programas que creamos en los projectos. Este documentación es importante porque será utilizado por otros programadores (y en algunos casos por nosostros mismos), para el desarrollo.

Este documento trara de como crear la documentación para que el javadoc pueda crear una documentación de nuestro código de manera correcta (como la del API de J2SE por ejemplo).

Obviamente el tutorial esta en ingles.

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Code Conventions for the JavaTM Programming Language

Las convenciones de código son importantes para los programadores por un número de razones:

• el 80% del coste del ciclo de vida de un software va al mantenimiento.
• Apenas cualquier software es mantenido por su vida entera por el autor original.
• Las convenciones de código mejoran la legibilidad del software, permitiendo entender el nuevo código más rápidamente y a fondo.
• Si usted envía su código fuente como producto, usted necesita cerciorarse de que también esté empaquetado y limpiao como cualquier otro producto que usted cree.

Nosotros utilizamos las convenciones de código para el lenguaje de programación de JavaTM:
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

Este Howto esta en ingles (el idioma oficial de la programación), no hay tradución por el momento, pero trata de cosas muy sencillas, pero que deben tomarse en cuenta a la hora de programar. Tales como:

• Nombres de archivos
• Organización de los archivos
• Identación del código
• Declaraciones
  
• Sentencias
• Comentarios
• Espacios en blancos
• Convencion de nombres
• Practicas de programación
• Ejemplos de código

Todos esto relacionado claro, con el formato que debe tener el código escrito por un equipo de programación.

Por suerte, existe una herramienta sencilla que automatiza este proceso (NO es que hagas de tu código un desatre :-D ). Jalopy es un formateador de código fuente para el lenguaje JAVA. El cual ayuda para tener una simetría (utilizando las conveción que definas) en tu código fuente. El cual comenzaré a utilizar en mis projectos.

http://jalopy.sourceforge.net/