Guia para codificar en JAVA

Para lograr la legibilidad de un programa es importante considerar aspectos tales como el nombre de los identificadores, escribir el código con cierta alineación y líneas en blanco en lugares apropiados así como realizar una buena documentación.

Identificadores

Los identificadores deben ser elegidos de tal manera que el solo nombre describa el uso que se dará dentro del programa, por tanto no es recomendable usar identificadores de una letra, excepto en el for, ni abreviaturas raras o ambiguas.
Además de eso es recomendable que se escriban:

• Empezando con mayúscula si se trata del nombre de una clase o interfaz, y empezando cada palabra en identificador con mayúscula. CírculoColoreado
• Sólo con mayúsculas si es el nombre de una constante. DIAS_HABILES
• Empezando con minúscula si es el nombre de cualquier otro identificador. De preferencia el nombre de cualquier método debe ser un verbo en infinitivo y el de todo atributo un sustantivo.primerJugador, asignarSueldo().

Archivos fuente

Cada programa en Java es una colección de uno o más archivos. El programa ejecutable se obtiene compilando estos archivos. En cada archivo especifica su contenido como sigue:

1. Los paquetes (instrucción package).
2. Los archivos de biblioteca (Instrucciones import).
3. Un comentario explicando el objetivo del archivo.
4. Las clases que defines en ese archivo.

Clases

Cada clase debe ir precedida por un comentario que explique su objetivo. Es recomendable especificar sus elementos como sigue:

1. Estructura de los objetos. Primero las variables y luego las constantes.
2. Elementos estáticos.
3. Constructores.
4. Métodos públicos y privados.
5. Métodos estáticos.
6. Clases internas.

Deja una línea en blanco después de cada método.
Todos los elementos deben estar precedidos por public, private o protected. Las variables deben ser privadas. Los métodos y las constantes pueden ser privados o públicos, según se requiera.

Métodos

Todo método excepto main debe empezar con un comentario en formato javadoc
El cuerpo de un método no debe exceder 30 líneas de código. Esto te obligará a dividir un método complejo en varios más sencillos.

Variables y Constantes

NO definas más de una variable por línea:

   int horas = 0, minutos = 0;  //Mal

es mejor:

   int horas = 0, 
       minutos = 0;

No uses números mágicos. Excepto -1, 0, 1 y 2 todas las literales numéricas dentro del código se consideran números mágicos.

if (p.horas() > 40)  ... // MAL

es mejor usar constantes definidas;

   final int HORAS = 40;

   .... 
   if (p.horas() > HORAS) ...        //Bien

Alineación y espacios en blanco

La alineación de instrucciones, se puede hacer de manera automática si se emplea el editor emacs (es recomendable modificar los tabuladores para que dejen sólo tres espacios en blanco).
En cualquier caso los elementos más importantes de ésta son:

• Todos los bloques deben estar alineados de tal manera que sean fácilmente distinguibles. Dentro de un bloque todas las instrucciones van a la misma altura.

  if (condición) {
     proposición_1;
     proposición_compuesta {
       proposición_2.1;
       proposición_2.2;
     }
     ..
     proposición_n;
  }

• En proposiciones compuestas el paréntesis que abre debe ir en la misma línea que empieza tal proposición. El paréntesis que cierra debe estar sólo en la última línea de la proposición y a la misma altura que la línea de inicio:

  while(hay_datos()) {
     proposiciones
  }

• Usa líneas en blanco para separar partes de un método que son lógicamente distintas.