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.