Categoría: Programación

Un código con buenos comentarios ayuda a su legibilidad como vimos en el artículo sobre cómo escribir código limpio y legible.

Cada bloque de código tiene un propósito, puede recibir parámetros y puede devolver un resultado. Toda esta información debería estar explicada brevemente en un bloque comentado, preferentemente antes de los bloques de ejecución. Por ejemplo:

// Función calculaPrecioFinalDeCarrito

//    Calcula el precio final del carrito ajustando impuestos y conversión de moneda

//

// Entrada: 

//    lista de productos, tipo de impuestos, tipo de moneda

// Salida: 

//    precio final a pagar por el cliente

function calculaPrecioFinalDeCarrito(listaProductos, tipoDeImpuestos, tipoMoneda) {

    var precioSinImpuestos = calculaPrecioDeListaDeProductos(listaProductos)

    var precioConImpuestos = calculaImpuestos(precioSinImpuestos, tipoDeImpuestos)

    var precioFinal = convierteAMoneda(precioConImpuestos, tipoMoneda)

    return precioFinal

}

Pero se debe ser breve y evitar comentar todo lo que hace el código línea a línea explicando sólo lo esencial.

Se debe explicar el porqué de las cosas y no cómo se hacen. Un buen código se da a entender por sí solo y no necesita extensos comentarios para ello.

En el artículo sobre cómo escribir código limpio y legible hablamos de la necesidad de coherencia cuando escribimos código.

Legibilidad por encima de la simplicidad

Algunos lenguajes de programación permiten realizar varias operaciones en una sola línea de código. Por ejemplo en Swift, Java o C++ podemos crear una instancia de clase, llamar a uno de sus métodos y realizar una comparación dependiendo del resultado de esa llamada todo en una sola línea de código. Esto reduce el número de líneas que pueda tener una función pero no mejora la legibilidad del código ya que quizás esas características del lenguaje de programación no son conocidas por todos los programadores.

Recuerda escribir el código para que lo pueda leer otra persona, porque incluso hay altas probabilidades que esa otra persona seas tú y puede que no entiendas tu propio código pasado unos meses o años.

Consistencia en la arquitectura de un proyecto

Una de las decisiones principales a tomar cuando empezamos un proyecto software es la de qué patrón de diseño utilizaremos para la arquitectura de nuestra aplicación.

Una vez tomada esta decisión debemos evitar mezclar arquitecturas ya que aumentamos la complejidad a la hora de entender cómo se organiza nuestro proyecto.