|
|
|
|
21.1 Comentarios
21.2. Comentarios para documentación
21.3. Una clase comentada
21.4 Convenciones de nombres
En Java existen comentarios de línea con // y bloques de comentario que comienzan con /* y terminan con */. Por ejemplo:
// Comentario de una linea
/* comienzo de comentario
continua comentario
fin de comentario */
El JDK proporciona una herramienta para generar páginas HTML de documentación a partir de los comentarios incluidos en el código fuente. El nombre de la herramienta es javadoc. Para que javadoc pueda generar los textos HTML es necesario que se sigan unas normas de documentación en el fuente, que son las siguientes:
 | Los comentarios de documentación deben empezar con /** y terminar con */. |
| Se pueden incorporar comentarios de documentación a nivel de clase, a nivel de variable (dato miembro) y a nivel de método. |
| Se genera la documentación para miembros public y protected. |
| Se pueden usar tags para documentar ciertos aspectos concretos como listas de parámetros o valores devueltos. Los tags se indican a continuación. |
| Tipo de tag | Formato | Descripción |
| Todos | @see | Permite crear una referencia a la documentación de otra clase o método. |
| Clases | @version | Comentario con datos indicativos del número de versión. |
| Clases | @author | Nombre del autor. |
| Clases | @since | Fecha desde la que está presente la clase. |
| Métodos | @param | Parámetros que recibe el método. |
| Métodos | @return | Significado del dato devuelto por el método |
| Métodos | @throws | Comentario sobre las excepciones que lanza. |
| Métodos | @deprecated | Indicación de que el método es obsoleto. |
Toda la documentación del API de Java está creada usando esta técnica y la herramienta javadoc.
import java.util.*;
/** Un programa Java simple.
* Envia un saludo y dice que día es hoy.
* @author Antonio Bel
* @version 1
*/
public class HolaATodos {
/** Unico punto de entrada.
* @param args Array de Strings.
* @return No devuelve ningun valor.
* @throws No dispara ninguna excepcion.
*/
public static void main(String [ ] args) {
System.out.println("Hola a todos");
System.out.println(new Date());
}}
SUN recomienda un estilo de codificación que es seguido en el API de Java y en estos apuntes que consiste en:
| Utilizar nombres descriptivos para las clases, evitando los nombres muy largos. |
| Para los nombres de clases poner la primera letra en mayúsculas y las demás en minúsculas. Por ejemplo: Empleado |
| Si el nombre tiene varias palabras ponerlas todas juntas (sin separar con - o _) y poner la primera letra de cada palabra en mayúsculas. Por ejemplo: InstrumentoMusical. |
| Para los nombres de miembros (datos y métodos) seguir la misma norma, pero con la primera letra de la primera palabra en minúsculas. Por ejemplo: registrarOyente. |
| Para las constantes (datos con el modificador final) usar nombres en mayúsculas, separando las palabras con _ |
|
|
|
|
Antonio Bel Puchol - antonio@abelp.net