Las convenciones y guía de estilos para el código fuente de Java

Todos los lenguajes definen un conjunto de reglas que definen el aspecto del código fuente. Estas convenciones cubren la indentación, comentarios, declaraciones, sentencias espacios en blanco, nomenclatura de nombres y prácticas de programación. Son una forma de mejorar la calidad del código que facilita su legibilidad y mantenibilidad.

Es importante seguir en todo el código fuente las mismas convenciones ya que en proyectos de larga duración la parte más importante es la de mantenimiento. El lenguaje de programación Java define sus propias convenciones que generalmente son aceptadas por los programadores. Las convenciones y guías de estilos de Java están recogidas en un documento de recomendable lectura y adhesión al programar. El documento ya tiene unos años pero las reglas existentes desde entonces no han cambiado aún cuando en el lenguaje se han añadido nuevos elementos como las lambdas en Java 8 o la posibilidad de omitir el tipo para las variables locales de Java 11.

Otros lenguajes como Python y C# definen sus propias convenciones bastante diferentes de las de Java que cambia significativamente el aspecto del código.

Convenciones de código en Java

Algunas recomendaciones en Java son:

• Una declaración de variable por línea, preferiblemente al inicio de los bloques de código.
• Ajustar la longitud de las líneas a 70 caracteres.
• Al ajustar líneas poner el punto de ruptura después de la coma, antes del operador, alinear la siguiente línea al inicio de la expresión de la línea anterior.
• No dejar un espacio en blanco entre el nombre del método y el paréntesis (, la llave de apertura { de inicio del bloque de código en la misma línea precedida por un espacio en blanco y la llave de cierre } indentada a la misma altura que el su bloque.
• Cada línea debería tener una sola sentencia.
• Usar líneas en blanco para separar secciones, entre definición de clases e interfaces, entre métodos, entre variables y la primera sentencia.
• Usar un espacio entre una palabra clave (if, for, while, …) y el paréntesis a continuación. Todos los operadores excepto el punto ., los de incremento ++ y decremento -- deben separarse de sus operandos con un espacio.
• Reglas de nomenclatura: los nombres de las clases debería ser nombres con la primera letra de cada palabra que lo compone en mayúscula, las interfaces siguen las mismas reglas de capitalización. Los métodos debería ser verbos con la primera letra en minúscula y las primeras letras de cada palabra en mayúscula. Las variables tiene la capitalización de la primera letra en minúscula y las primeras letras de cada palabra en mayúscula con nombre cortos pero significativos. Las variables de una sola letra deben ser evitadas salvo los casos comúnmente reconocidos como iteradores (i, j, k). Las constantes deben estar con todas las letras en mayúscula con las palabras separadas con una barra baja _.

Aparte de las convenciones del propio lenguaje Java otras organizaciones como Google y Spring definen sus propias convenciones cambiando ligeramente las de Java por las preferencias de sus desarrolladores. Cualquier otra empresa según las preferencias acordadas por sus desarrolladores también puede definir sus variaciones a las convenciones generales de Java, salvo cambiar drásticamente las convenciones generales no hay ningún inconveniente en incorporar pequeñas variaciones lo importante es que todos los desarrolladores sigan las mismas convenciones en todo el código fuente.

• Google Java Style Guide
• Spring Framework Code Style

Como ejemplo de pequeñas variaciones prefiero declarar las variables en el momento del primer uso en el que se le puede asignar un valor en vez del inicio del bloque de código o con las pantallas de gran resolución en mi opinión el límite de línea máximo es más amplio que 70 caracteres.

Ejemplos de código con convenciones de Java

Este es el aspecto de algunos pequeños trozos de código siguiendo las convenciones definidas por Java.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

package java.awt;

import java.awt.peer.CanvasPeer;

public class Main {

   public static void main(String[] args) {
      System.out.println("Hello World!");
   }
}

---

int level = 0;  // indentation level
int size = 0;   // size of table

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

---

function(longExpression1, longExpression2, longExpression3,
         longExpression4, longExpression5);


longName1 = longName2 * (longName3 + longName4 - longName5)
            + 4 * longname6;


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

---

if ((condition1 && condition2)
       || (condition3 && condition4)
       || !(condition5 && condition6)) {
   doSomething();
}

if (condition) {
   statements;
} else if (condition) {
   statements;
} else if (condition) {
   statements;
}

for (initialization; condition; update) {
   statements;
}

while (condition) {
   statements;
}

switch (condition) {
    case ABC:
        statements;
        /* falls through */
    case DEF:
        statements;
        break;
    case XYZ:
        statements;
        break;
    default:
        statements;
        break;
}

Idioma español o inglés para dar nombres

Otro punto a tener en cuenta en el código fuente es si utilizar palabras del lenguaje materno, en nuestro caso español, o utilizar palabras solo en inglés para dar nombres a clases, métodos y variables. Es válido utilizar cualquiera de las dos opciones siempre que se utilice en todo el código fuente.

Aún así yo prefiero utilizar solo inglés por dos motivos:

• El inglés es un lenguaje compacto que normalmente utiliza palabras compuestas por menos caracteres que el español.
• Algunos términos de programación son comúnmente conocidos por sus palabras en inglés como los métodos get y set o patrones de diseño como Repository o Aggregator, mezclar otro lenguaje con las palabras en inglés queda raro (getPrecio(), findProductoByNombreAndActivo(), CompraRepository).

1
2
3

CompraRepository compraRepository;
BigDecimal precio = producto.getPrecio();
Host nominasHost = host;

Por suerte en Java refactorizar cualquier nombre es bastante más sencillo y rápido con el soporte de los IDE. En un lenguaje dinámico hacer un renombrado es básicamente buscar y reemplazar todas las ocurrencias con riesgo de omitir alguna que cause un «error de compilación» en tiempo de ejecución del código erróneo.

Herramientas automatizadas

Los entornos integrados de desarrollo ofrecen la funcionalidad de formatear el código de forma automática con las reglas que tengan configuradas. En IntelliJ se configuran en File > Settings > Editor > Code Style para que todos los desarrolladores utilicen las mismas reglas, estas se pueden compartir con las opciones de exportar e importar en otro ordenador. En estos paneles hay multitud de opciones para personalizar el formateo del código.

Existen herramientas que automatizan la comprobación de las normas elegidas en un proyecto en el código desde la línea de comandos con la herramienta de construcción como Gradle y aplicable también al código subido al repositorio de control de versiones con la herramienta de integración continua ya sea Jenkins, GitLab u otra. Una de ellas es PMD, otra Checkstyle, ambas generan un informe con los errores de convenciones con el que es muy fácil realizar los cambios para corregirlos.

• Análisis estático de código con PMD y un ejemplo

Otras recomendaciones

Aparte de las convenciones es recomendable seguir unas pautas sencillas como guía al escribir código para entre otras cosas que su legibilidad sea más sencilla.

• Buenas prácticas de programación sencillas en el código fuente