Código limpio con comentarios útiles

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.

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.