Los programas Java pueden tener dos tipos de comentarios: los comentarios de implementaci�n y los comentarios de documentaci�n. Los comentarios de implementaci�n son aquellos encontrados en C++, que est�n delimitados por /*...*/, y //. Los comentarios de documentaci�n son �nicos de Java y est�n delimitados por /**...*/. Los comentarios de documentaci�n se pueden extraer a ficheros HTML usando la herramienta javadoc.
Los comentarios de implementaci�n se han creado para comentar c�digo o para comentarios sobre la implementaci�n particular. Los comentarios de documentaci�n se han creado para definir la especificaci�n del codigo, desde un perspectiva libre de implementaci�n para ser le�do por desarrolladores que podr�an no tener necesariamente a mano el c�digo fuente.
Los comentarios deber�an usarse para una introducci�n del c�digo y proporcionar informaci�n adicional que no est� disponible en el propio c�digo. Los comentarios s�lo deber�an tener informaci�n que sea relevante para leer y entender el programa. Por ejemplo, informaci�n sobre como est� construido el paquete correspondiente o en qu� directorio reside no deber�a ser incluida como comentarios.
Las discusiones no triviales o decisiones de dise�o no obvias son apropiadas, pero debemos evitar la duplicidad de informaci�n que est� presente en el c�digo. Es demasiado f�cil que los comentarios redundantes se queden anticuados. En general, debemos evitar cualquier comentario que se pueda quedar anticuado cuando el c�digo evolucione.
|
Nota:
La frecuencia en los comentarios algunas veces refleja una pobre calidad de c�digo. Cuando nos sintamos obligados a llenarlo de comentarios, debemos considerar la reescritura del c�digo para hacerlo m�s claro. Los comentarios no deben encerrarse en grandes cajas dibujadas con asteriscos u otros caracteres. Los comentarios nunca deber�an incluir caracteres especiales como saltos de p�gina, etc. |
�Formatos de Implementaci�n de Comentarios
Los programas pueden tener cuatro estilos de implementaci�n de comentarios:
�Bloque de Comentarios
Los bloques de comentarios se usan para proporcionar descripciones de ficheros, m�todos, estructuras de datos y algoritmos. Los bloques de comentarios podr�an usarse al principio de cada fichero y antes de cada m�todo. Tambi�n pueden usarse en otros lugares, como dentro de los m�todos. Los bloques de comentarios dentro de una funci�n o m�todos deber�an estar identados al mismo nivel que el c�digo que describen. Un bloque de comentario deber�a ir precedido por una l�nea en blanco para configurar un apartado del resto del c�digo:
/* * Here is a block comment. */
Los bloques de comentarios pueden comenzar con /*-, lo que le dice al indent(1) que es el principio de un bloque de comentarios y que no deber�a ser reformateado, por ejemplo:
/*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */
|
Nota:
Si no usamos indent(1), no tenemos que usar /*- en nuestro c�digo o hacer cualquier otra concesi�n a la posibilidad de que algui�n pudiera ejecutar indent(1) sobre nuestro c�digo. |
�C�mentarios de una l�nea
Los comentarios cortos pueden aparecen como un� s�la l�nea identada al nivel del c�digo que la sigue. Si un comentario no se puede escribir en una s�la l�nea, deber�a seguir el formato de los bloques de comentario. Un comentario de una s�la l�nea deber�a ir precedido de una l�nea en blanco. Aqu� tenemos un ejemplo:
if (condition) {
/* Handle the condition. */
...
}
�Comentarios finales
Los comentarios muy cortos pueden aparecer en la misma l�nea que el c�digo que describen, pero deber�an separarse lo suficiente de las sentencias. Si aparece m�s de un comentario en el mismo trozo de c�digo, deber�an estar identados a la misma altura. Aqu� tenemos un ejemplo:
if (a == 2) {
return TRUE; /* special case */
} else {
return isPrime(a); /* works only for odd a */
}
�Comentarios de final de l�nea
El delimitador de comentario // puede comentar una l�nea completa o una l�nea parcial. No deber�a usarse en l�neas consecutivas para comentar texto; sin embargo, si puede usarse en l�neas consecutivas para comentar secciones de c�digo. Abajo tenemos ejemplos de los tres estilos:
if (foo > 1) {
// Do a double-flip.
...
}
else{
return false; // Explain why here.
}
//if (bar > 1) {
//
// // Do a triple-flip.
// ...
//}
//else{
// return false;
//}
�Comentarios de Documentacion
Los comentarios de documentaci�n describen clases Java, interfaces, constructores, m�todos y campos. Cada comentario de documentaci�n va dentro de los delimitadores de comentario /**...*/, con un comentario por clase, interface o miembro. Este comentario debe aparecer justo antes de la declaraci�n:
/**
* The Example class provides ...
*/
public class Example { ...
Observa que las clases e interfaces de alto nivel no est�n identados, mientras que los miembros si lo est�n. La primera l�nea del comentario de documento (/**) para las clases e interfaces no est� identada; las subsecuentes l�neas del comentario de documentaci�n tendr�n un espacio de identaci�n (para alinear verticalmente los astericos). Los miembros, incluyendo constructores, tienen cuatro espacios para la primera l�nea de comentario de documentaci�n y 5 espacios despu�s.
Si necesitamos dar informaci�n sobre una clase, un interface, una variable o un m�todo que no es apropiada para documetnaci�n, usamos una implementaci�n de bloque de comentario, o una declaraci�n de una l�nea inmediatamente despu�s de la declaraci�n. Por ejemplo, los detalles sobre la implementaci�n de una clase deber�an ir en un bloque de comentario seguido por la sentencia class, no en el comentario de documentaci�n de la clase.
Los comentarios de documentaci�n no deber�an colocarse dentro de un bloque de definici�n de un m�todo o constructor porque Java asocia los comentarios de documetnaci�n con la primera declaraci�n que hay despu�s del comentario...