Este documento describe la codificación básica en Java, incluyendo que los archivos Java tienen la extensión .java, los diferentes tipos de comentarios, y cómo se usan los comentarios de documentación (etiquetados con @) para generar documentación con javadoc. Explica que cada clase se almacena normalmente en un archivo separado con el mismo nombre de la clase, y que los comentarios de documentación proveen información sobre autores, parámetros, excepciones, versiones y más.

1. Programación Básica en Java
By Jorge González Tapia
Contenido
Programación Básica en Java .............................................................................................................. 1
2.1. Codificación Java ...................................................................................................................... 1
2.1.1. Archivos .java.................................................................................................................... 1
2.1.2. Comentarios .......................................................................................................................... 1
2.1. Codificación Java
Un programa en Java consiste de una serie de declaraciones de clases e Interfaces, cada
una de las cuales se compone de declaraciones de métodos y Variables. Estas
declaraciones se presentan formando un texto o código que Es almacenado en un archivo
fuente. Aun cuando las declaraciones de varias Clases y/o interfaces pueden ser
almacenadas en el mismo archivo fuente, típicamente cada declaración se almacena en
un archivo separado. Esto no se debe solo a preferencia, sino que también se relaciona
con la forma en que las clases de Java se cargan cuando un programa se ejecuta.
2.1.1. Archivos .java
Los archivos fuente siempre tienen nombres con la terminación .java. La primera parte del
nombre del archivo es el nombre de la clase o interfaz declarada en el propio archivo. Por
ejemplo, una clase Test se almacenaría en un archivo Test.java. Si un archivo contiene la
declaración de más de una clase o interfaz, el archivo debe ser nombrado a partir de una
de ellas, la cual debe ser la única clase o interfaz pública (public) en el archivo.
2.1.2. Comentarios
Los comentarios en Java tienen tres formas:
// Este es un comentario de una sola línea /* Este es un comentario multilinea */
/** Este es un comentario para documentación */
Los comentarios para documentación se reconocen mediante la herramienta

2. javadoc, la cual lee los comentarios de documentación y automáticamente genera páginas
HTML conteniendo una versión limpiamente formateada de la información de los
comentarios. Cada página documenta una clase y lista cada variable miembro junto con
cualquier información o comentario provisto.
Las bibliotecas de Java se documentan usando los comentarios para documentación y la
herramienta javadoc.
Los comentarios para documentación empiezan con una marca /** y Terminan con */.
Pueden extenderse por múltiples líneas, pero no pueden ser anidados. Solo los
comentarios para declaración inmediatamente antes de la declaración de clases,
interfaces, variables miembro y métodos se reconocen por javadoc como comentarios
para documentación. En cualquier otro lado, un comentario para documentación se
considera solo como un comentario multilınea.
Dentro de un comentario para documentación pueden aparecer varias etiquetas que
permiten procesar la información del comentario en formas especificas por la herramienta
javadoc. Cada etiqueta se marca por un símbolo @, y debe comenzar en una línea
aparte. Las siguientes etiquetas se encuentran disponibles:
@author. Nombre del o los autores del código que se comenta. El nombre del autor se
escribe simplemente como texto:
@author Daniel López
Pueden utilizarse varias etiquetas con diferentes autores, o varios nombres pueden ser
considerados en la misma etiqueta:
@author Daniel Lopez, Javier Jimenez
@deprecated. Se usa para indicar que la siguiente clase o método se ha cambiado de una
versión anterior del código, y será removido en versiones futuras. La etiqueta puede ser
seguida de una corta explicación:
@deprecated No será disponible en siguientes versiones Idealmente, @deprecated debe
seguirse de una etiqueta @see que dirijaal lector al punto de reemplazo. Esta etiqueta es
adicionalmente reconocida por el compilador de Java, lo que genera un mensaje de
advertencia (warning) si el código se utiliza.
@exception.
Provee de información sobre las excepciones que puedenarrojarse a partir de un método.
Un nombre de excepción puede aparecer Después de la etiqueta seguida de un
comentario de texto.
@exception IndexOutOfBoundsException Intento de accesar un elemento invalido
Un comentario para documentación puede contener varias etiquetas
@exception.
@param. Provee información sobre parámetros de métodos y constructores.

3. La etiqueta es seguida del nombre del par´ametro y de un comentario:
@param size Tamano de una estructura de datos
Estas etiquetas solo deben aparecer en comentarios precediendo m´etodos
y constructores. Idealmente, debe haber una etiqueta por cada
par´ametro, present´andose en el mismo orden de los par´ametros.
@return. Documenta el valor de retorno de un m´etodo.
@return El indice de un elemento identificado
El comentario es texto simple. Un comentario para documentaci´on
debe solo contener una etiqueta @return, ya que solo puede haber un
solo valor de retorno.
@see. Provee una referencia cruzada a otra clase, interfaz, m´etodo,
variable o URL. Las siguientes son referencias v´alidas:
13
@see java.lang.Integer
@see Integer
@see Integer#intValue
@see Integer#getInteger(String)
@see <a href="info.html">Vease aqui para mayor informacion</a>
Las clases e interfaces pueden ser referenciadas tanto por su nombre
como por el nombre completo del paquete al que pertenecen. Las
variables y m´etodos miembro pueden referenciarse mediante a˜nadir su
nombre al nombre de la clase siguiendo el s´ımbolo #. Los URLs pueden
aparecer si se hace un formato utilizando las etiquetas <a>...</a> de
HTML. M´ultiples etiquetas @see pueden aparecer en el mismo comentario.
@since. Se usa para establecer cuando una característica particular
fue incluida (por ejemplo, desde cuándo se ha hecho disponible). La etiqueta se sigue por
un texto dando la información requerida:
@since JDK1.0
@version. Se utiliza para dar información sobre la versión de la revisión actual del código
siendo comentado. El formato para la información sobre la versión no está especificado, y
se deja al programador.
Una convención no oficial que se está utilizando cada vez más es aquella en que el
número de la versión se sigue por la fecha de liberación (release date):
@version 1.2 20.8.1997
Solo una etiqueta de versión puede aparecer dentro de un comentario.
El texto incluido en un comentario para documentación puede también marcarse con
etiquetas HTML usadas para controlar la apariencia del texto, incluyendo
<code>...</code> (que delimita el texto utilizando la letra para código de programación), y
<p> (que indica el comienzo de un nuevo
párrafo, y que se utiliza frecuentemente también como delimitador de la forma
<p>...</p>).
Consúltese libros sobre HTML para detalles referentes a la notación de ese lenguaje.
La siguiente declaración de una clase ilustra el uso de los comentarios
para documentación:
/** Esta es una clase de prueba para mostrar el uso de comentarios para

4. documentacion.
@author Daniel Lopez
@see java.lang.String
@version 1.0 10.8.1997
*/
public class Comment1 {
/** Retorna el argumento multiplicado por 2.
@param x El valor entero a ser duplicado.
@return El argumento del metodo multiplicado por 2.
@deprecated Sera removido en la siguiente version de la clase.
@see #multiplyByTwo
*/
public int times2 (int x) {
return x*2;
}
/** Retorna el argumento multiplicado por 2, reemplazando
la version anterior de este metodo.
@param x El valor entero a ser duplicado.
@return El argumento del metodo multiplicado por 2.
*/
public int multiplyByTwo (int x) {
return 2*x;
}
/** La funcion main usada para probar la clase.
@param args argumentos de linea de comando (no usados)
*/
public static void main(String[] args) {
Comment1 test = new Comment1();
int n = test.times2(5);
n = test.multiplyByTwo(10);
System.out.println(s);
}
/** Una cadena de caracteres utilizada por la funcion
<code>main</code>.
*/
static String s = "Hello";
}