Comentarios, documentación y convenciones de nombres en Java

Comentarios

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 */

Comentarios para documentación

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 la 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.

Una clase comentada

import java.util.*;

/** Un programa simple en Java.
 * Envía un saludo e indica que día es hoy.
 * @author Mundo Telecomunicaciones
 * @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());
    }

}

Convenciones de nombres

ORACLE recomienda un estilo de codificación que es seguido en el API de Java y en este post, y 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 _ solamente.

REFERENCIAS:       arrakis