Formato del Código en Código Limpio

Cuando escribimos código debemos seguir unas reglas a la hora de darle forma para que gane en legibilidad.

Número de Lineas por Archivo

Los archivos pequeños se entiende mejor que los grandes.

Un intervalo aconsejable, que no obligatorio, está entre 200 y 500 lineas por archivo.

Símil de Periódico/Código

Haciendo el símil entre un periódico y el código sacamos las siguientes conclusiones:

  • El Titulo/Nombre Clase indica de que trata lo que vamos a leer. Nos da una aproximación a ver si estamos en el punto correcto.
  • Los primeros párrafos/trozos de código, ofrecerán una sinopsis de la historia, ocultando detalles y mostrando conceptos generales que se desglosarán más adelante.
  • Según avanzamos en el articulo/código, los detalles irán aumentando llegando a la parte final del articulo/código donde encontraremos las funciones más a nivel inferior, más complejas y especificas.

 

Un periódico se compone de muchos artículos por pagina, para que sea manejable. Si un periódico fuera un único articulo extenso, no lo leeríamos.

Igual pasa en nuestro código. Si tenemos una clase donde engloba todo dentro, nos resultara muy difícil ver lo que nos interesa en cada momento.

Separación Vertical

Dejar lineas en blanco que separan acciones distintas dentro de la clase, mejoran visualmente la comprensión del código. Cada linea en blanco nos marca que habrá un nuevo concepto independiente del anterior.

 

En el siguiente caso vemos que al no tener separación entre los métodos, nos dificulta visualmente a identificarlos de manera rápida.

Densidad Vertical

Implica asociaciones dentro del mismo ámbito. En el siguiente ejemplo se ve claramente que tenemos dos atributos dentro de la clase persona y los identificamos a simple vista.

En el siguiente caso, perdemos esa rapidez a la hora de identificar los atributos y debemos navegar entre el código para sacar algo en claro.

Distancia Vertical

Los conceptos relacionados entre si deben mantenerse juntos verticalmente.  Esta regla no funciona con conceptos de archivos independientes. Por tanto, no debe separar conceptos relacionados en archivos independientes a menos que tenga un motivo de peso.

Las variables deben declararse de la forma más próxima a su uso.

Las variables en las funciones han de declararse en la parte superior de cada función.

Las variables de control de bucle deben declararse en la instrucción del bucle.

Las variables de instancia se declararan en un punto conocido para que todo el mundo sepa donde buscarlas, normalmente en la parte superior de la clase en Java y en la parte inferior en C++.

 

Determinados conceptos de código deben estar próximos a otros. Tienen una afinidad conceptual concreta. Esta afinidad se puede basar en una dependencia directa, como cuando una función invoca a otra, o cuando sea una variable. También se puede generar porque un grupo de función realiza una operación similar.

Orden Vertical

Si una función invoca a otra, deben estar verticalmente próximas, y la función de invocación debe estar por encima de la invocada. Así el programa fluye con normalidad, leyendo de arriba abajo el código como un libro. Los conceptos más importantes y globales aparecen  antes, aumentando el nivel de detalles a medida que bajamos en el código.

Formato Horizontal

Como norma, no se debe hacer scroll en la pantalla para ver el código horizontalmente.

Tampoco pasarse a escribir lineas enormes por tener un monitor muy ancho. Un limite aceptable son 120 caracteres por linea.

Apertura y Densidad Horizontal

Se usan espacios en blanco horizontal para asociar elementos directamente relacionados y separar otros con una relación menos estrecha.

En el ejemplo se ve como rodeamos el operador += entre espacio dejando visualmente separados ambas partes del operador.

Se aprecia también que después de la apertura del  paréntesis y antes del cierre de los mismos no dejamos espacios para que se aprecie agrupamiento.

Alineación Horizontal

Se aprecia la homogeneidad del código al escribir todo alineado horizontalmente.

Sangrado

El sangrado nos indica la jerarquía del código.

Se sangran un nivel hacia la derecha las partes de código pertenecientes al ente superior al que pertenece.

Sin el sangrado los programas serian prácticamente ilegibles.

**No romper el sangrado ni en las instrucción de bucles breves. Se pierde legibilidad  en el código.

Reglas de Equipo

Cada uno de nosotros tenemos nuestras reglas favoritas, pero al trabajar en equipo, el equipo manda.

Antes de cada proyecto, los programadores deberían reunirse para definir un estilo de código y que todos escriban con el mismo estilo.

Todos los archivos del proyecto deberán seguir las mismas reglas manteniendo un estilo coherente y dinámico.