003 - Comentarios

003 - Comentarios

·

2 min read


¿Por qué comentar?

En los lenguajes de programación, hacer comentarios de tu código resulta una práctica bastante útil y eficiente pues permite que otros desarrolladores puedan entender tu código al leerlo y ver los comentarios.


Comentarios en Javascript

Para hacer un comentario en Javascript tenemos 2 opciones:

Comentario de una sola línea

Este se escribe usando doble barra "//"

let x = 10;    // Este es un comentario

Comentario de varias líneas

Este se scribe usando una barra y un asterisco para abrir el comentario "/*" y un asterisco y una barra para cerrarlo "*/"

const phi = 1.618034;
/*
    Hola, soy un comentario
    de varias líneas
*/

Buenas prácticas al comentar

Al momento de comentar código en Javascript (y los demás lenguajes de programación) debemos tener en cuenta ciertas prácticas que nos permitirán realizar mejores comentarios:

"¿Por qué?" en vez de "¿Qué?"

Cuando comentas un código, debes explicar más bien porque ese código está escrito de esa manera, en vez de explicar qué es lo que hace (Eso ya lo hace el código en sí)

//    Esta funcion toma 2 números x e y, y luego retorna su producto
function multiply(x,y) {
    return x*y
};

// Calcula ingresos mensuales
function ingreso_mensual(salario, gastos){
    return salario - gastos
};

Ejemplos de comentarios que podrían mejorar. No hace falta comentarlos pues el código ya explica explícitamente que hace.

Describir el comportamiento de un bloque de código

En el código pueden haber funciones complicadas, pero que su trabajo sea explícito. Es decir, que solo haría falta explicar cómo funciona:

/*
  * Devuelve a veces b.
  *
  * @param {number} a : Cantidad de veces que se escribe b.
  * @param {number} b : El número que se va a repetir a veces.
  * @return {number} c : Resultado de la operación.
*/
function myFunction(a,b){
    ...
}

Sé consistente

Esto viene de la mano con saber comentar; debes de ser consistente en tu estilo de comentario: Usar el mismo idioma y forma de comentar para que sea entendido por cualquier desarrollador

Evita comentar

Aunque suene raro, un código optimizado debe de tener la menor cantidad de comentarios posibles, pues esto significa que el propio código es explicativo y puede ser comprendido por cualquier desarrollador.
Trata de usar variables y nombres de funciones que sean autodescriptivas y así reducirás la cantidad de comentarios en tu código.


En futuros artículos profundizaré sobre otras buenas prácticas al comentar y algunos ejemplos explicativos.

¡Gracias por leer!

Referencias

Calidad del código - Javascript Info

Comentarios de código - Lenguaje JS

Did you find this article valuable?

Support Luidrawly Daily Blog by becoming a sponsor. Any amount is appreciated!