Comentarios de código

Cuando comenzamos a programar, por lo general, se nos suele decir que es una buena práctica mantener comentado nuestro código con anotaciones que faciliten la comprensión de las tareas que realizamos y los problemas que pretendemos solucionar, ya que el código que creamos no suele ser muy bueno, ni mucho menos descriptivo, puesto que estamos en fase de aprendizaje.

A medida que conseguimos destreza programando, notaremos que los comentarios son cada vez más prescindibles, sin embargo, conviene no dejar de comentar, sino en su lugar, aprender a comentar mejor.

Una serie de consejos a tener presentes a la hora de dejar comentarios en nuestro código:

• No comentes detalles redundantes. No escribas lo que haces, escribe por qué lo haces.
• Mejor nombrar variables/funciones/clases de forma descriptiva que usar comentarios para describirlas.
• Sé conciso y concreto. Resume. No escribas párrafos si no es absolutamente necesario.
• Intenta usar siempre el mismo idioma y estilo de comentarios.
• Si modificas código, revisa también los comentarios. Comentarios desactualizados, son inservibles.

Tipos de comentarios

En Javascript existen dos tipos de comentarios: los comentarios de una sola línea y los comentarios de múltiples líneas.

• Una línea: Comienza con // y sólo comenta la linea actual desde donde se escribe.
• Múltiples líneas: Comentarios extensos. Comienzan por /* y comentará todo el texto que escribamos hasta que cerremos el comentario con un */.

Veamos un ejemplo:

// Comentarios cortos de una sola línea. Suelen explicar la línea siguiente.
let a = 1;

let x = 45; // También se utilizan al final de una línea.

/* Por otro lado, existen los comentarios múltiples de varias líneas consecutivas.
   Suelen utilizarse para explicaciones largas que requieren bastante
   espacio porque se mencionan gran cantidad de cosas :-) */

Ejemplos

Comentar código también es un arte que debe ser aprendido, ya que al principio es muy fácil cometer errores y comentar en exceso o no ser concreto al comentar. No suele ser grave porque los comentarios no afectan al funcionamiento del programa, pero en equipos de trabajo donde hay varios programadores suele ser molesto para los programadores con más experiencia.

Un ejemplo de comentario que suele ser contraproducente es aquel que se limita a decir lo que hacemos en la línea siguiente:

// Declaramos una variable llamada x ❌
let x = 50;

// La mostramos por consola ❌
console.log(x);

// Cambiamos su valor multiplicando por 0,5 ❌
x = x * 0.5;

Estos comentarios pueden ser útiles para el programador novato que comienza a programar y necesita recordar lo que hace porque aún no conoce bien la sintaxis de programación, de hecho muchos de los comentarios del tema de introducción son así (para ayudar al programador que recién empieza a programar), pero el objetivo real de un comentario no debe ser recordar que hace una línea de código, sino conocer porque lo estamos realizando o que representa lo que estamos haciendo:

let x = 50; // Establecemos el precio del producto ❌

console.log(x);

x = x * 0.5; // Lo rebajamos al 50% ❌

Sin embargo, hay una opción todavía mejor que conecta con uno de los temas que veremos más adelante. Poner nombres descriptivos a las variables debería ser algo obligatorio a lo que acostumbrarnos, puesto que puede ahorrarnos muchos comentarios y tiempo, simplificar el código considerablemente y hacerlo mucho más legible y con menos ambigüedades:

let precio = 50; ✅

console.log(precio);

let oferta = precio * 0.5; ✅

En este fragmento de código, no utilizamos comentarios porque el nombre de las variables ya ayuda a entender el código y lo hace autoexplicativo. De esta forma, generamos menos código (e incluso comentarios) y se entiende igualmente. En los siguientes temas, veremos una serie de consejos a la hora de nombrar variables, funciones u otros elementos dentro de la programación.