Sorteo de Varias CD-KEYS de juegos para STEAM.

Buenas a todos fieles seguidores,

vamos a sortear varias claves para STEAM de diversos juegos de SQUARE-ENIX durante el mes de Marzo.

Las reglas para participar son las siguientes:


1. DEUS EX HUMAN REVOLUTION: STEAM-KEY

Ser seguidor de twitter de @waitsignal y hacer algún comentario con el hashtag #concursoelwaitsignal

GANADOR Paddoc#F1

2. HITMAN ABSOLUTION: STEAM-KEY

Ser seguidor de http://jabatogames.blogspot.com y escribir un comentario en este post sobre qué plataforma de juegos más os convence. Usar el hashtag #concursoelwaitsignal

GANADOR  Alejandro Pineda Medina

3. MURDERED SOULS SUSPECT: STEAM-KEY

Ser seguidor del canal de youtube asociado al blog: http://www.youtube.es/elwaitsignal y dejar algún comentario en los vídeos del canal con el hastag #concursoelwaitsignal






* Nota:

El administrador podrá dejar fuera del concurso a aquellos mensajes de mal gusto.
Las fechas del sorteo serán los días 16, 26 y 30 de Marzo respectivamente.
A cada usuario se le asignará un número por orden de mensaje y se realizará el sorteo en directo en retransmisión por http://www.twitch.tv/elwaitsignal con la página http://www.alazar.info/generador-de-sorteos.

* Nota 2: He tenido problemas con twitch ya que han reiniciado las contraseñas y tal y he tenido que volver a configurarlo todo. El sorteo se hará mañana 26 a las 18:00.

Se añadirán más juegos y sorteos próximamente.

Suerte a todos.

SORTEO FINALIZADO. ENHORABUENA A LOS GANADORES. EN LOS COMENTARIOS ESTÁN LOS RESULTADOS.

ORDEN DE PARTICIPANTES. (Se irá actualizando progresivamente):

1. Deus Ex Human

Valors
ivalice27
Rurru
Tachi
totxtreme
Teskiya
Fatima Carlet 
Alejandro Pineda
pulmonarro
Paddock #F1
Mohd Ghanayem
Voltioz Craft
David 'Dage' Goodman
César L
Rosa Millán



2. Hitman Absolution


Fran Chalé
Tachi
Sara del ojo
Alejandro Pineda Medina
Ion
Mohd Ghanayem
lucas gamallo
Dage DGG
Alejandro Miret
Samer Troller
Dsda Sdad
shinefix154
Juan Carlos Magdalena

3. Murdered.



Tachi211
Sara del ojo
TheMrxale
Carol Berruh
Renée
Pulmonarro
Jose Javier Carrasco Gallego
1000101V
Ion
Mohd Ghanayem

Solucionado. Provider (0x80004005) Error no especificado. Conectar con base de datos ASP.

Frecuentemente me ocurría que cuando trabajaba con asp y accedía a la base de datos, estando esta abierta, me arrojaba el siguiente error:
Tipo de error:
Provider (0x80004005)
Error no especificado
/nombredeldirectorio/nombredelarchivo.asp, línea 5
Este error logré solucionarlo incluyendo la siguiente instrucción al abrir la base de datos.
("DRIVER={Microsoft Access Driver (*.mdb)}; Database Locking Mode=0; DBQ=" & Server.MapPath("datos/deportes.mdb"))
Específicamente lo que permite seguir trabajando y que no tengas que reiniciar el equipo está en la leyenda "Database Locking Mode = 0"

Java - Estándares de programación. Nomenclaturas. Buena praxis.

1. Estándares de programación

1.1. Introducción

El objeto del presente documento es el establecimiento de los estándares o convenciones de programación empleados en el desarrollo de software sobre la plataforma Java. Este modelo de programación está basado en los estándares recomendados por Sun Microsystems, que han sido difundidos y aceptados ampliamente por toda la comunidad Java, y que han terminado por consolidarse como un modelo estándar de programación de facto.

Estas normas son muy útiles por muchas razones, entre las que destacan:


  • Facilitan el mantenimiento de una aplicación. Dicho mantenimiento constituye el 80% del coste del ciclo de vida de la aplicación.

  • Permite que cualquier programador entienda y pueda mantener la aplicación. En muy raras ocasiones una misma aplicación es mantenida por su autor original.

  • Los estándares de programación mejoran la legibilidad del código, al mismo tiempo que permiten su compresión rápida.



1.2. Organización de ficheros

Las clases en Java se agrupan en paquetes. Estos paquetes se deben organizar de manera jerárquica, de forma que todo código desarrollado para el Ayuntamiento de Málaga tendrá que estar incluido dentro del paquete "eu.malaga". 
Dentro del paquete principal las clases se organizarán en subpaquetes en función del área, organismo o sección del Ayuntamiento al que pertenezca el código desarrollado. Por ejemplo, si estamos desarrollando un servicio web de inscripción a un curso de programación Java del IMFE las clases de dicho servicio se incluirían en el paquete "eu.malaga.imfe.webservices.cursojava" o similar.

Un fichero consta de secciones que deben estar separadas por líneas en blanco y comentarios opcionales que identifiquen cada sección.

Deben evitarse los ficheros de gran tamaño que contengan más de 1000 líneas. En ocasiones, este tamaño excesivo provoca que la clase no encapsule un comportamiento claramente definido, albergando una gran cantidad de métodos que realizan tareas funcional o conceptualmente heterogéneas.

1.2.1. Fichero fuente Java (.java)

Cada fichero fuente Java debe contener una única clase o interfaz pública. El nombre del fichero tiene que coincidir con el nombre de la clase. Cuando existan varias clases privadas asociadas funcionalmente a una clase pública, podrán colocarse en el mismo fichero fuente que la clase pública. La clase pública debe estar situada en primer lugar dentro del fichero fuente.
En todo fichero fuente Java distinguimos las siguientes secciones:


  • Comentarios de inicio.

  • Sentencia de paquete.

  • Sentencias de importación.

  • Declaraciones de clases e interfaces.



1.2.1.1. Comentarios de inicio

Todo fichero fuente debe comenzar con un comentario que incluya el nombre de la clase, información sobre la versión del código, la fecha y el copyright. El copyright indica la propiedad legal del código, el ámbito de distribución, el uso para el que fue desarrollado y su modificación. 

Dentro de estos comentarios iniciales podrían incluirse adicionalmente comentarios sobre los cambios efectuados sobre dicho fichero (mejora, incidencia, error, etc.). Estos comentarios son opcionales si los ficheros están bajo un sistema de control de versiones bien documentado, en caso contrario se recomienda su uso. Estos comentarios constituyen el historial de cambios del fichero. Este historial es único para cada fichero y permitirá conocer rápidamente el estado y la evolución que ha tenido el fichero desde su origen.

A continuación se muestra un comentario de inicio para la clase "JceSecurity.java".


/*
 * @(#)JceSecurity.java 1.50 04/04/14
 * 
 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

/**
 * This class instantiates implementations of JCE engine classes from
 * providers registered with the java.security.Security object.
 *
 * @author Jan Luehe
 * @author Sharon Liu
 * @version 1.50, 04/14/04
 * @since 1.4
 */


1.2.1.2. Sentencias de paquete

La primera línea no comentada de un fichero fuente debe ser la sentencia de paquete, que indica el paquete al que pertenece(n) la(s) clase(s) incluída(s) en el fichero fuente. Por ejemplo,


package javax.crypto;


1.2.1.3. Sentencias de importación

Tras la declaración del paquete se incluirán las sentencias de importación de los paquetes necesarios. Esta importación de paquetes obligatorios seguirá el siguiente orden:


  • Paquetes del JDK de java.

  • Paquetes de utilidades no pertenecientes al JDK de Java, de frameworks de desarrollo o de proyectos opensource tales como apache, hibernate, springframework, etc.

  • Paquetes desarrollados para el Ayuntamiento de Málaga.

  • Paquetes de la aplicación.



Se recomienda minimizar en la medida de lo posible el uso de importaciones del tipo "package.*", pues dificultan la comprensión de las dependencias existentes entre las clases utilizadas por la aplicación. En caso contrario, se recomienda utilizar comentarios de línea tras la importación.


import java.io.*; // BufferedReader, PrintWriter, FileInputStream, File
import java.util.ArrayList;

import org.apache.log4j.Logger;
import org.apache.lucene.analysis.Analyzer;
import es.provincia.organismo.corporativas.atlas.vo.AgendaVO;
import es.provincia.organismo.atlas.vo.AnuncioVO;
import es.provincia.organismo.atlas.vo.OrganigramaVO;


1.2.1.4. Declaraciones de clases e interfaces

La siguiente tabla describe los elementos que componen la declaración de una clase o interfaz, así como el orden en el que deben estar situados.

Elementos de declaración de una clase / interfazDescripción
Comentario de documentación de la clase/interfaz /** ... */Permite describir la clase/interfaz desarrollada. Necesario para generar la documentación de la api mediante javadoc.
Sentencia class / interface
Comentario de implementación de la clase/interfaz, si es necesario /* ... */Este comentario incluye cualquier información que no pueda incluirse en el comentario de documentación de la clase/interfaz.
Variables de clase (estáticas)En primer lugar las variables de clase públicas (public), después las protegidas (protected), posteriormente las de nivel de paquete (sin modificador), y por último las privadas (private).
Variables de instanciaPrimero las públicas (public), después las protegidas (protected), luego las de nivel de paquete (sin modificador), y finalmente las privadas (private).
Constructores
MétodosDeben agruparse por funcionalidad en lugar de agruparse por ámbito o accesibilidad. Por ejemplo, un método privado puede estar situado entre dos métodos públicos. El objetivo es desarrollar código fácil de leer y comprender.


1.3. Sangría

Como norma general se establecen 4 caracteres como unidad de sangría. Los entornos de desarrollo integrado (IDE) más populares, tales como Eclipse o NetBeans, incluyen facilidades para formatear código Java.

1.3.1. Longitud de línea

La longitud de línea no debe superar los 80 caracteres por motivos de visualización e impresión.

1.3.2. División de líneas

Cuando una expresión ocupe más de una línea, esta se podrá romper o dividir en función de los siguientes criterios,


  • Tras una coma.

  • Antes de un operador.

  • Se recomienda las rupturas de nivel superior a las de nivel inferior.

  • Alinear la nueva línea con el inicio de la expresión al mismo nivel que la línea anterior.

  • Si las reglas anteriores generan código poco comprensible, entonces estableceremos tabulaciones de 8 espacios.



Ejemplos:


unMetodo(expresionLarga1, expresionLarga 2, expresionLarga 3, 
        expresionLarga 4, expresionLarga 5);

if ((condicion1 && condicion2)
        || (condicion3 && condicion4)
        ||!(condicion5 && condicion6)) {
    unMetodo();
}


1.4. Comentarios

Distinguimos dos tipos de comentarios: los comentarios de implementación y los de documentación. 

1.4.1. Comentarios de implementación

Estos comentarios se utilizan para describir el código ("el cómo"), y en ellos se incluye información relacionada con la implementación, tales como descripción de la función de variables locales, fases lógicas de ejecución de un método, captura de excepciones, etc.

Distinguimos tres tipos de comentarios de implementación:


  • Comentarios de bloque:

    Permiten la descripción de ficheros, clases, bloques, estructuras de datos y algoritmos.
    
    /*
     * Esto es un comentario
     * de bloque
     */


  • Comentarios de línea:

    Son comentarios cortos localizados en una sola línea y tabulados al mismo nivel que el código que describen. Si ocupa más de una línea se utilizará un comentario de bloque. Deben estar precedidos por una línea en blanco.
    
    /* Esto es un comentario de línea */
    
    // Esto es otro comentario de línea


  • Comentario a final de línea

    Comentario situado al final de una sentencia de código y en la misma línea.
    
    int contador = 4 + 10;  // Inicialización del contador
    contador++;   /* Incrementamos el contador */




1.4.2. Comentarios de documentación

Los comentarios de documentación, también denominados "comentarios javadoc", se utilizan para describir la especificación del código, desde un punto de vista independiente de la implementación, de forma que pueda ser consultada por desarrolladores que probablemente no tengan acceso al código fuente.

El apartado 2 de este documento describe el uso de comentarios de documentación.


1.5. Declaraciones

1.5.1. Una declaración por línea

Se recomienda el uso de una declaración por línea, promoviendo así el uso de comentarios. Ejemplo, 


int idUnidad;   // Identificador de la unidad organizativa
String[] funciones; // Funciones de la unidad


1.5.2. Inicialización

Toda variable local tendrá que ser inicializada en el momento de su declaración, salvo que su valor inicial dependa de algún valor que tenga que ser calculado previamente.


int idUnidad = 1;
String[] funciones = { "Administración", "Intervención", "Gestión" };


1.5.3. Localización

Las declaraciones deben situarse al principio de cada bloque principal en el que se utilicen, y nunca en el momento de su uso. 


public void unMetodo() {
 int contador = 0;  // inicio del método

 ...
}


La única excepción a esta regla son los índices de los bucles "for", ya que, en Java, pueden incluirse dentro de la propia sentencia "for".


for (int i=0; contador<10; i++) {
 ...
}

Se debe evitar el uso de declaraciones que oculten a otras declaraciones de ámbito superior. 


int contador = 0;  // Inicio del método

public void unMetodo() {
 
 if (condicion) {
  int contador = 2;  // ¡¡ EVITAR !!
  ...
 }
 ...
}


1.5.4. Declaración de clases / interfaces

Durante el desarrollo de clases / interfaces se deben seguir las siguientes reglas de formateo:


  • No incluir ningún espacio entre el nombre del método y el paréntesis inicial del listado de parámetros.

  • El carácter inicio de bloque ("{") debe aparecer al final de la línea que contiene la sentencia de declaración.

  • El carácter fin de bloque ("}") se sitúa en una nueva línea tabulada al mismo nivel que su correspondiente sentencia de inicio de bloque, excepto cuando la sentencia sea nula, en tal caso se situará detrás de "{".

  • Los métodos se separarán entre sí mediante una línea en blanco.



public classe ClaseEjemplo extends Object {

 int variable1;
 int variable2;
 
 public ClaseEjemplo() {
  variable1 = 0;
  variable2 = 1;
 }
 ...
}


1.6. Sentencias

Cada línea debe contener como máximo una sentencia. Ejemplo,


int contador++;
int variable--;


Las sentencias pertenecientes a un bloque de código estarán tabuladas un nivel más a la derecha con respecto a la sentencia que las contiene.

El carácter inicio de bloque "{" debe situarse al final de la línea que inicia el bloque. El carácter final de bloque "}" debe situarse en una nueva línea tras la última línea del bloque y alineada con respecto al primer carácter de dicho bloque.

Todas la sentencias de un bloque deben encerrarse entre llaves "{ ... }", aunque el bloque conste de una única sentencia. Esta práctica permite añadir código sin cometer errores accidentalmente al olvidar añadir las llaves. Ejemplo,


if (condicion) {
 variable++;
}


La sentencia "try/catch" siempre debe tener el formato siguiente,


try {
    sentencias;
} catch (ClaseException e) {
    sentencias;
}


En el bloque "catch" siempre se imprimirá una traza de error indicando el tipo de excepción generada y posteriormente se elevará dicha excepción al código invocante, salvo que la lógica de ejecución de la aplicación no lo requiera.

Siempre se utilizará el bloque "finally" para liberar recursos y para imprimir trazas de monitorización de fin de ejecución.


try {
    sentencias;
} catch (ClaseException e) {
    sentencias;
} finally {
    sentencias;
}



1.7. Espacios en blanco

Las líneas y espacios en blanco mejoran la legibilidad del código permitiendo identificar las secciones de código relacionadas lógicamente.

Se utilizarán espacios en blanco en los siguientes casos:

Entre una palabra clave y un paréntesis. Esto permite que se distingan las llamadas a métodos de las palabras clave. Por ejemplo:


while (true) {
    ...
}


Tras cada coma en un listado de argumentos. Por ejemplo:


objeto.unMetodo(a, b, c); 


Para separar un operador binario de sus operandos, excepto en el caso del operador ("."). Nunca se utilizarán espacios entre los operadores unarios (p.e., "++" o "--") y sus operandos. Por ejemplo:


a += b + c;

a = (a + b) / (c + d);

contador++;


Para separar las expresiones incluidas en la sentencia "for". Por ejemplo:


for (expresion1; expresion2; expresion3)



Al realizar el moldeo o "casting" de clases. Ejemplo:


Unidad unidad = (Unidad) objeto;


1.8. Nomenclatura de identificadores

Las convenciones de nombres de identificadores permiten que los programas sean más fáciles de leer y por tanto más comprensibles. También proporcionan información sobre la función que desempeña el identificador dentro del código, es decir, si es una constante, una variable, una clase o un paquete, entre otros.

1.8.1. Paquetes

Se escribirán siempre en letras minúsculas para evitar que entren en conflicto con los nombres de clases o interfaces. El prefijo del paquete siempre corresponderá a un nombre de dominio de primer nivel, tal como: es, eu, org, com, net, etc. 

El resto de componentes del paquete se nombrarán de acuerdo a las normas internas de organización de la empresa: departamento, proyecto, máquina, sección, organismo, área, etc.

Generalmente se suele utilizar el nombre de dominio de Internet en orden inverso. Cuando dicho nombre contenga un carácter "-", este se sustituirá por el carácter "_".

Ejemplos:


es.provincia.organismo1.festivaldecine
es.provincia.organismo2.vivienda
es.provincia.organismo3.juventud
es.provincia.organismo3.formacion
es.provincia.organismo3.gestionturistica

java.util.ArrayList
java.util.Date
java.util.Properties

javax.servlet.http.HttpServletRequest
javax.servlet.http.HttpServletResponse


1.8.2. Clases e interfaces

Los nombres de clases deben ser sustantivos y deben tener la primera letra en mayúsculas. Si el nombre es compuesto, cada palabra componente deberá comenzar con maýusculas.
Los nombres serán simples y descriptivos. Debe evitarse el uso de acrónimos o abreviaturas, salvo en aquellos casos en los que dicha abreviatura sea más utilizada que la palabra que representa (URL, HTTP, etc.).

Las interfaces se nombrarán siguiendo los mismos criterios que los indicados para las clases. Como norma general toda interfaz se nombrará con el prefijo "I" para diferenciarla de la clase que la implementa (que tendrá el mismo nombre sin el prefijo "I").


class Ciudadano
class OrganigramaDAO
class AgendaService
class IAgendaService


1.8.3. Métodos

Los métodos deben ser verbos escritos en minúsculas. Cuando el método esté compuesto por varias palabras cada una de ellas tendrá la primera letra en mayúsculas.


public void insertaUnidad(Unidad unidad);
public void eliminaAgenda(Agenda agenda);
public void actualizaTramite(Tramite tramite)


1.8.4. Variables

Las variables se escribirán siempre en minúsculas. Las variables compuestas tendrán la primera letra de cada palabra componente en mayúsculas.

Las variables nunca podrán comenzar con el carácter "_" o "$". Los nombres de variables deben ser cortos y sus significados tienen que expresar con suficiente claridad la función que desempeñan en el código. Debe evitarse el uso de nombres de variables con un sólo carácter, excepto para variables temporales. 


Unidad unidad;
Agenda agenda;
Tramite tramite;


1.8.5. Constantes

Todos los nombres de constantes tendrán que escribirse en mayúsculas. Cuando los nombres de constantes sean compuestos las palabras se separarán entre sí mediante el carácter de subrayado "_".


int LONGITUD_MAXIMA;
int LONGITUD_MINIMA;


1.9. Prácticas de programación

1.9.1. Visibilidad de atributos de instancia y de clase

Los atributos de instancia y de clase serán siempre privados, excepto cuando tengan que ser visibles en subclases herederas, en tales casos serán declarados como protegidos.

El acceso a los atributos de una clase se realizará por medio de los métodos "get" y "set" correspondientes, incluso cuando el acceso a dichos atributos se realice en los métodos miembros de la clase.


public class Unidad {

 private int id;
 private String nombre;
 ...

 public void actualizaUnidad(Unidad unidad) {
  this.setId(unidad.getId());
  this.setNombre(unidad.getNombre());
 }

 ...
}


1.9.2. Referencias a miembros de una clase

Evitar el uso de objetos para acceder a los miembros de una clase (atributos y métodos estáticos). Utilizaremos en su lugar el nombre de la clase. Por ejemplo:


metodoUtilidad();    // Acceso desde la propia clase estática
ClaseUtilidad.metodoUtilidad(); // Acceso común desde cualquier clase


1.9.3. Constantes

Los valores constantes (literales) nunca aparecerán directamente en el código. Para designar dichos valores se utilizarán constantes escritas en mayúsculas y se declararán, según su ámbito de uso, o bien en una Clase de constantes creada para tal efecto, o bien en la clase donde sean utilizadas.


// Uso incorrecto
codigoErrorUsuarioNoEncontrado = 1;
...
switch (error) {
  case codigoErrorUsuarioNoEncontrado:
   ...
}

// Uso correcto
public final int CODIGOERROR_USUARIONOENCONTRADO = 1;
...
switch (error) {
  case CODIDOGERROR_USUARIONOENCONTRADO:
   ...
}


1.9.4. Asignación sobre variables

Se deben evitar las asignaciones de un mismo valor sobre múltiples variables en una misma sentencia, ya que dichas sentencias suelen ser difíciles de leer.


int a = b = c = 2;  // Evitar


No utilizar el operador de asignación en aquellos lugares donde sea susceptible de confusión con el operador de igualdad. Por ejemplo:


// INCORRECTO
if ((c = d++) == 0) { }

// CORRECTO
c = d++;
if (c == 0) { }


No utilizar asignaciones embebidas o anidadas. Ejemplo:


c = (c = 3) + 4 + d;  // Evitar


debería escribirse


c = 3;
c = c + 4 + d; 



1.9.5. Otras prácticas


  • Paréntesis

    Es una buena práctica el uso de paréntesis en expresiones que incluyan distintos tipos de operadores para evitar problemas de precedencia de operadores. Aunque la precedencia de operadores nos pueda parecer clara, debemos asumir que otros programadores no tengan un conocimiento exhaustivo sobre las reglas de precedencia.
    
    if (w == x && y == z)     // INCORRECTO
    if ((w == x) && (y == z)) // CORRECTO


  • Valores de retorno

    Los valores de retorno tendrán que ser simples y comprensibles, de acuerdo al propósito y comportamiento del objeto en el que se utilicen.
    
    // INCORRECTO
    public boolean esProgramador(Empleado emp) {
    
     if (emp.getRol().equals(ROL_PROGRAMADOR)) {
      return true;
     } else {
      return false;
     }
    
    }
    
    // CORRECTO
    public boolean esProgramador(Empleado emp) {
    
     boolean esUnProgramador = false;
    
     if (emp.getRol().equals(ROL_PROGRAMADOR)) {
      esUnProgramador = true;
     }
    
     return esUnProgramador;
    }


  • Expresiones en el operador condicional ternario

    Toda expresión compuesta, por uno o más operadores binarios, situada en la parte condicional del operador ternario deberá ir entre paréntesis. Ejemplo:
    
    (x >= y) ? x : y;


  • Comentarios especiales (TODO, FIXME, XXX)

    Utilizaremos XXX para comentar aquella porción de código que, aunque no tenga mal funcionamiento, requiera modificaciones. Usaremos FIXME para señalar un bloque de código erróneo que no funciona. Emplearemos TODO para comentar posibles mejoras de código, como puedan ser las debidas a optimizaciones, actualizaciones o refactorizaciones.




2. Documentación: javadoc

Se aconseja, como buena práctica de programación, incluir en la entrega de la aplicación la documentación de los ficheros fuente de todas las clases. Dicha documentación será generada por la herramienta "javadoc".

La herramienta "javadoc" construirá la documentación a partir de los comentarios (incluidos en las clases) encerrados entre los caracteres "/**" y "*/". Distinguimos tres tipos de comentarios javadoc, en función del elemento al que preceden: de clase, de variable y de método.

Dentro de los comentarios "javadoc" podremos incluir código html y etiquetas especiales de documentación. Estas etiquetas de documentación comienzan con el símbolo "@", se sitúan al inicio de línea del comentario y nos permiten incluir información específica de nuestra aplicación de una forma estándar.

Como norma general utilizaremos las siguientes etiquetas:


  • @author Nombre

    Añade información sobre el autor o autores del código.

  • @version InformacionVersion

    Permite incluir información sobre la versión y fecha del código.

  • @param NombreParametro Descripción

    Inserta el parámetro especificado y su descripción en la sección "Parameters:" de la documentación del método en el que se incluya. Estas etiquetas deben aparecer en el mismo orden en el que aparezcan los parámetros especificados del método. Este tag no puede utilizarse en comentarios de clase, interfaz o campo. Las descripciones deben ser breves.

  • @return Descripción

    Inserta la descripción indicada en la sección "Returns:" de la documentación del método. Este tag debe aparecer en los comentarios de documentación de todos los métodos, salvo en los constructores y en aquellos que no devuelvan ningún valor (void).

  • @throws NombreClase Descripción

    Añade el bloque de comentario "Throws:" incluyendo el nombre y la descripción de la excepción especificada. Todo comentario de documentación de un método debe contener un tag "@throws" por cada una de las excepciones que pueda elevar. La descripción de la excepción puede ser tan corta o larga como sea necesario y debe explicar el motivo o motivos que la originan.

  • @see Referencia

    Permite incluir en la documentación la sección de comentario "See also:", conteniendo la referencia indicada. Puede aparecer en cualquier tipo de comentario "javadoc". Nos permite hacer referencias a la documentación de otras clases o métodos.

  • @deprecated Explicación

    Esta etiqueta indica que la clase, interfaz, método o campo está obsoleto y que no debe utilizarse, y que dicho elemento posiblemente desaparecerá en futuras versiones. "javadoc" añade el comentario "Deprecated" en la documentación e incluye el texto explicativo indicado tras la etiqueta. Dicho texto debería incluir una sugerencia o referencia sobre la clase o método sustituto del elemento "deprecado".

  • @since Version

    Se utiliza para especificar cuando se ha añadido a la API la clase, interfaz, método o campo. Debería incluirse el número de versión u otro tipo de información.


El siguiente ejemplo muestra los tres tipos de comentarios "javadoc",


/**
 * UnidadOrganizativa.java:
 * 
 *  Clase que muestra ejemplos de comentarios de documentación de código. 
 * 
 * @author jlflorido
 * @version 1.0, 05/08/2008
 * @see documento "Normas de programación v1.0"
 * @since jdk 5.0 
 */
public class UnidadOrganizativa extends PoolDAO {

    /** Trazas de la aplicación */
    private Logger log = Logger.getLogger(UnidadOrganizativa.class);

    /** Identificador de la unidad organizativa */
    private int id;
 
    /** Nombre de la unidad organizativa */
    private String nombre;

    /** Obtiene el identificador de esta unidad organizativa */
    public int getId() {
        return id;
    }

    /** Establece el identificador de esta unidad organizativa */
    public void setId(int id) {
        this.id = id;
    }
 
    /** Obtiene el nombre de esta unidad organizativa */
    public String getNombre() {
        return nombre;
    }

    /** Establece el nombre de esta unidad organizativa */
    public void setNombre(String nombre) {
        this.nombre = nombre;
    }
 
    /**
     * Inserta la unidad organizativa en el sistema.
     * 
     * @param unidad Unidad organizativa a insertar
     * @throws Exception Excepción elevada durante el proceso de inserción
     */
    public void insertarUnidad(UnidadOrganizativa unidad) throws Exception{
  
        log.debug("-> insertarUnidad(UnidadOrganizativa unidad)");
  
        Connection conn = null;
        PreparedStatement pstmt = null;
        StringBuffer sqlSb = null;
  
        try {
            conn = this.dameConexion();
      
            sqlSb = new StringBuffer("")
            .append("INSERT INTO ORG.UNIDAD_ORGANIZATIVA ")
            .append("(ID, NOMBRE) VALUES (?, ?)");
      
            pstmt = conn.prepareStatement(sqlSb.toString());
            pstmt.setInt(1, unidad.getId());
            pstmt.setString(2, unidad.getNombre());
            pstmt.executeUpdate();
   
        } catch (Exception e) {

            log.error("Error: error al insertar la unidad. " +
            "Descripción:" + e.getMessage(), e);

            throw e;

        } finally {

            log.debug("<- insertarUnidad(UnidadOrganizativa unidad)");

        }
    }
}


La documentación generada por "javadoc" será la siguiente:

a) Página índice de toda la documentación generada:




b) Documentación de la clase "UnidadOrganizativa.java":








Fuente: http://javafoundations.blogspot.com.es/2010/07/java-estandares-de-programacion.html#1_8_nomenclatura