Comentarios de código

Cuando comenzamos a programar, una buena práctica es mantener comentado nuestro código con anotaciones que faciliten la lectura y comprensión de las tareas que realizamos y los problemas que pretendemos solucionar. A medida que conseguimos destreza programando, notaremos que los comentarios son cada vez más prescindibles, sin embargo, conviene no dejar de comentar y en su lugar, aprender a comentar mejor.

Existen una serie de consejos a tener presentes a la hora de comentar:

  • consiso y concreto. Resume, no escribas largos párrafos a menos que sea necesario.
  • No comentes cosas redundantes. No escribas lo que haces, escribe por qué lo haces.
  • Intenta usar siempre el mismo idioma y estilo de comentarios.

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 un var o un console.log, sino conocer porque lo estamos realizando o que representa lo que estamos haciendo en las siguientes líneas:

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(x);

precio = precio * 0.5;     // Rebaja del 50%

No obstante, en el siguiente tema 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. Escribe en Emezeta.com, es profesor en la Oficina de Software Libre de la Universidad de La Laguna y dirige el curso de Programación web FullStack de EOI en Tenerife (Canarias). En sus ratos libres, busca GIF de gatos en Internet.