Comentarios
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...
Tutoriales
