Convenciones de Código Java

Importancia de las Convenciones de Código

• Las convenciones de código mejoran la legibilidad del software.
• Facilitan la comprensión rápida y exhaustiva de código nuevo.
• Aproximadamente el 80% del costo del código de un programa se destina a su mantenimiento.
• Resultan esenciales para la distribución de código fuente como producto.
• Es imprescindible que cada persona que escribe software las siga.

Extensiones de Ficheros Java

• Fuente Java utiliza la extensión .java.
• Bytecode de Java utiliza la extensión .class.

Indentación y Longitud de Línea

• Se deben emplear cuatro espacios como unidad de indentación.
• Los tabuladores deben ser cada 8 espacios, y no 4.
• Evitar líneas de más de 80 caracteres debido a la mala gestión por terminales y herramientas.
• En la documentación, las líneas no deben superar los 70 caracteres.

Ruptura de Líneas al Indentar

• Al romper una expresión que no cabe en una línea, hacerlo después de una coma.
• Es preferible romper antes de un operador.
• Utilizar roturas de alto nivel, más a la derecha que el "padre", en lugar de bajo nivel.
• Alinear la nueva línea con el comienzo de la expresión al nivel de la línea anterior.
• Si las reglas anteriores generan código confuso, usa 8 espacios de indentación.

Ejemplos de Indentación al Romper Líneas

• Ejemplo de declaración de métodos:

unMetodo(expresionLarga1, expresionLarga2, expresionLarga3,
         expresionLarga4, expresionLarga5);

• Ejemplo preferido de ruptura de líneas en expresiones aritméticas:

nombreLargo1 = nombreLargo2 * (nombreLargo3 + nombreLargo4
                                 - nombreLargo5) + 4 * nombreLargo6; // PREFERIDA

Otros ejemplos de indentación

• Ejemplo de indentación de declaraciones de métodos (convencional):

unMetodo (int anArg, Object anotherArg, String yetAnotherArg,
         Object andStillAnother) {
    ...
}

• Ejemplo de indentación de declaraciones de métodos (8 espacios adicionales):

private static synchronized metodoDeNombreMuyLargo (int unArg,
         Object otroArg, String todavíaOtroArg,
         Object unOtroMas) {
    ...
}

Indentación en Sentencias Condicionales (if)

• Al saltar líneas en sentencias if, seguir la regla de los 8 espacios.
• La indentación convencional (4 espacios) dificulta la visualización del cuerpo del condicional.
• No utilizar la primera forma de indentación presentada, prefiriendo la segunda o tercera.

Comentarios en Java

• Java soporta dos tipos de comentarios: de implementación y de documentación.
• Los de implementación también se encuentran en C++, delimitados por /*...*/ y //.
• Los de documentación, exclusivos de Java, usan la notación /**...*/ y se exportan a HTML con Javadoc.
• Los de implementación son para comentar código o detalles de una implementación específica.
• Los de documentación describen la especificación del código, independientemente de la implementación.
• No se deben encerrar en grandes cuadrados dibujados con asteriscos.
• No deben incluir caracteres especiales como backspace.

Formatos de Comentarios de Implementación

• Hay cuatro estilos: de bloque, de una línea, de remolque y de fin de línea.

• Los comentarios de bloque se usan para dar descripciones de ficheros, métodos, estructuras de datos y algoritmos.

• Los comentarios de bloque se pueden usar al comienzo de un fichero o antes de un método.

• Se pueden escribir en otro lugares, tales como el interior de los métodos, deben ser indentados al mismo nivel que el código que describen.

• Deben estar precedidos por una línea en blanco.

• Formato de comentario de bloque:

/*
- Aquí hay un comentario de bloque.
- /

• Los comentarios de una sola línea comentan código al nivel del código que siguen

if (condicion) {

    /* Código de la condición. */
}

• En los comentarios de remolque: incluir comentarios muy pequeños en la misma línea que describen, pero lo suficientemente separadas de las sentencias.

if (a == 2) {
    return TRUE;  /* caso especial */
} else {
    return isPrime(a); /* caso general */
}

• Comentario de fin de línea, el delimitador es //, puede convertir una linea en comentario.

if (foo > 1) {
    // Hacer algo.
}

Declaraciones: Cantidad y Tipos

• Es preferible una declaración por línea, facilitando los comentarios.

int nivel; // nivel de indentación
int tam;  // tamaño de la tabla

• En lugar de:

int level, size;

• No se deben declarar diferentes tipos en la misma línea.

Inicialización y Colocación de Variables

• Es recomendable inicializar las variables locales donde se declaran.
• La única razón para no hacerlo es si el valor inicial depende de cálculos que deben ocurrir.
• Las declaraciones deben estar al principio de los bloques de código (entre llaves).

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

• Excepción: los índices de bucles for se pueden declarar en la sentencia for.
• Evitar declaraciones locales que ocultan declaraciones de niveles superiores.

Declaración de Clases e Interfaces

• No debe haber espacio en blanco entre el nombre de un método y el paréntesis de su lista de parámetros.
• La llave de apertura { aparece al final de la línea de declaración.
• La llave de cierre } comienza una nueva línea indentada para ajustarse a su sentencia de apertura.
• Si no existen sentencias entre las llaves, la llave de cierre } debe aparecer inmediatamente después de la de apertura {.
• Los métodos se separan con una línea en blanco.

Sentencias Simples y Compuestas

• Cada línea debe contener como mucho una sentencia.
• Las sentencias compuestas deben tener listas de sentencias encerradas entre llaves { sentencias }
• Las sentencias encerradas deben indentarse un nivel más que la sentencia compuesta.
• La llave de apertura se pone al final de la línea que comienza la sentencia compuesta.
• La llave de cierre empieza una nueva línea y se indentan al mismo nivel que la compuesta.
• Usar llaves en todas las sentencias, incluso las simples, cuando forman parte de una estructura de control.

Sentencias de Retorno

• La sentencia return con un valor no debe usar paréntesis, a menos que hagan el valor de retorno más obvio:

return;
return miDiscoDuro.size();
return (tamanyo ? tamanyo : tamanyoPorDefecto);

Sentencias Condicionales (if, if-else, if else-if else)

• Las sentencias condicionales deben tener una de las siguientes formas (siempre con llaves):

if (condicion) {
  sentencias;
}

if (condicion) {
  sentencias;
} else {
  sentencias;
}

if (condicion) {
  sentencia;
} else if (condicion) {
   sentencia;
} else {
   sentencia;
}

• Se deben usar siempre llaves en las sentencias if, evitando la forma propensa a errores:

Condicional Ternario

• Permite tomar decisiones en una sola línea, como alternativa corta al if-else.

• El formato es: condición ? expresión_si_verdadero : expresión_si_falso;

• Ejemplo:

int edad = 25;
String msg = (edad >= 18) ? "Mayor de edad" : "Menor de edad";
System.out.println(msg);

• Componentes:

1. La condición a evaluar (expresión booleana).
2. El valor/expresión si la condición es verdadera.
3. El valor/expresión si la condición es falsa.

Sentencia Switch

• La sentencia switch debe tener el siguiente formato:

switch (condicion) {
    case ABC:
        sentencias;
        /* este caso se propaga */
    case DEF:
        sentencias;
        break;
    case XYZ:
        sentencias;
        break;
    default:
        sentencias;
        break;
}

• Siempre comentar cada caso que se propaga, se debe añadir la sentencia break aunque sea redundante.

Sentencias de Repetición (for, while, do-while)

• For:

for (inicializacion; condicion; actualizacion) {
 sentencias;
}

• For vacío (si el trabajo se realiza en las cláusulas):

for (inicializacion; condicion; actualizacion);

• While:

while (condicion) {
 sentencias;
}

• Do While:

do {
 sentencias;
} while (condicion);

Sentencias Try-Catch

• Format:

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

• La sentencia Try se puede se seguir de finally:

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

Líneas en Blanco

• Mejoran la facilidad de lectura separando secciones de código relacionadas lógicamente.
• Debe usar dos entre las secciones de un fichero fuente, las definiciones de clases e interfaces.
• Se usa una entre métodos, las variables locales de un método y su primera sentencia, antes de un comentario de bloque y entre las secciones lógicas de un método.

Espacios en Blanco

• Deben ser usados después de las palabras clave del lenguaje seguido por un parentesis.
• Notar que no se debe usar un espacio en blanco entre el nombre de un método y su paréntesis de apertura (esto ayuda a distinguir palabras claves de llamadas a métodos).
• Debe aparecer un espacio en blanco después de una coma en las listas de argumentos
• Todos los operadores binarios se deben separar de sus operandos con espacio en blanco.

Convenciones de Nombres

• Hacen los programas más entendibles.
• Util en la funcion de un identificador, ejemplo: Cuando es una constante, un paquete o una case.
• Los prefijos de los paquetes deben empezar en minuscula ASCII.
• Los nombres de las clases deben ser sustantivos, deben usar palabras completas, evitar acrónimos y abreviaturas.
• Los métodos deben ser verbos, verbos + sustantativos.
• Los nombres de las variables declaradas como constantes deben ir totalmente en mayúsculas separando las palabras con un subguión.
• Excepto las constatntes, todas las instancias y variables de clase o método empezarán con minúscula. Los nombres de variables no deben empezar con los caracteres subguión "_" o signo del dólar "$".
• Los nombres de las variables deben ser cortos pero con significado. Los nombres de variables, en caso de ser temporal, deben ser i, j, k, m, y n para enteros.