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, ya 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 nombres de variables/funciones/clases descriptivas que comentarios descriptivos.
  • conciso y concreto. Resume. No escribas párrafos si no es absolutamente necesario.
  • Intenta usar siempre el mismo idioma y estilo de comentarios.
  • Con el tiempo, los comentarios no se suelen mantener (modificar), el código sí.

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.

  • El primero de ellos se caracteriza porque comienza con // y sólo comenta la linea actual desde donde se escribe.
  • El segundo tipo se utiliza para hacer comentarios extensos que ocuparán varias líneas. Comienza 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.
var a = 1;

var 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
var 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:

var 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:

var precio = 50;

console.log(precio);

var 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.

Manz
Publicado por Manz

Docente, divulgador informático y freelance. Autor de Emezeta.com, es profesor en la Universidad de La Laguna y dirige el curso de Programación web FullStack y Diseño web FrontEnd de EOI en Tenerife (Canarias). En sus ratos libres, busca GIF de gatos en Internet.