Comentarios en programación: Consejos y uso correcto.



Ya sea que tengas años de experiencia en programación o que estés comenzado, hay una gran posibilidad de que hayas estado haciendo un mal uso de los comentarios en programación. Te pido que no te saltes nada de esta lectura, estoy seguro de que lo que aprenderás te servirá para crear mejores programas sin importar el lenguaje de programación que utilices.

Esto es lo que aprenderás en este artículo:

¿Qué son los comentarios en un programa y para qué sirve?

Técnicamente, son bloques de texto que serán ignorados por el compilador (no serán ejecutados por la computadora). Se crearon con el objetivo permitir a los programadores incluir textos que ayudarán a cualquier programador a comprender mejor el programa.

Se usan para que otros programadores o incluso nosotros mismos tengamos una idea más clara sobre el funcionamiento de un programa. Cualquiera puede escribir comentarios en un programa, pero muy pocas personas pueden escribir comentarios que sea realmente útiles, al inicio yo escribía malos comentarios, pero ahora voy a resumirte todo lo que he aprendido para crear comentarios que resulten muy útiles.

Como agregar un comentario en PHP, JavaScript, etc.

Seguramente ya sabes esto, existen dos tipos de comentarios: de línea y de bloque, cada lenguaje de programación tiene su propia sintaxis, pero usualmente se usa esto // para un comentario de línea y /* */ para comentarios de bloques. Aquí hay un ejemplo:

/*
Este es un bloque de comentario, se usa para colocar una
descripcion que abarca varias lineas.
*/
function ImprimirEnPantalla( $texto  ){
  if ($texto == '') {
    return;                                             //Este es un comentario en linea
  }
  $texto_limpio = htmlspecialchars($texto, ENT_QUOTES); //Se usan para comentarios cortos
  echo $texto_limpio;
}

Ya vimos como colocar un comentario, ahora vamos a ver algunos consejos sobre cómo debes utilizar los comentarios adecuadamente en tus programas.

Comentarios o código bien escrito.

Como ya mencioné antes, los comentarios ayudan a comprender mejor el código de un programa, pero en ocasiones los comentarios son necesarios únicamente porque el código ha sido mal escrito.

Piensa en alguna idea, si tienes que escribirla en papel posiblemente elijas palabras que sean difíciles de comprender y necesites explicarla a cualquier persona que la lea. Otra persona podría escribir la misma idea, pero usando otras palabras y otra estructura, de forma que, aun siendo la misma idea, cualquier otra persona pueda leerla y comprenderla sin necesidad de una explicación.

Lo mismo sucede con el código, puede ser que tu código funcione bien, pero sea difícil de leer y comprender y por eso necesita una explicación (comentarios), veamos este ejemplo:

for($i=0;$i<count($p);$i++)
{
 imp($p[$i]);
}

El código anterior fue escrito en PHP y posiblemente entiendas las instrucciones: recorres un arreglo y luego llamas a una función para cada elemento, pero ¿tienes alguna idea de porque se hace eso y cuál será el resultado? Veamos ahora el mismo código, pero con comentarios:

/*
Recorrer la variable $p que contiene una lista de párrafos a imprimir
en la pagina web.
*/
for($i=0;$i<count($p);$i++)
{
  //Imprimimos cada párrafo con la función imp
 imp($p[$i]);
}

Ahora sí, gracias a los comentarios, entendemos que estamos imprimiendo los párrafos o bloques de texto que están en una variable de tipo Array. Pero estos comentarios no serían necesarios si nuestro código fuera más legible, veamos un código diferente, pero que hace la misma tarea.

for($i=0; $i < count($ListaParrafos); $i++)
{
  ImprimirEnPantalla($ListaParrafos[$i]);
}

Como puedes ver, este código no necesita comentarios para que cualquier programador de PHP entienda que es lo que está haciendo el código y cuál sería el resultado. Siempre que puedas escribe código autoexplicativo que no necesite comentarios para entender su propósito o resultado.

¿Cómo deben ser los comentarios en programación?

Aunque nuestro código esté bien escrito y sea fácil de entender, en ocasiones necesitamos agregar algunos comentarios para que nuestro código sea mejor comprendido para otros programadores o incluso para nosotros mismos. Ahora voy a mostrarte algunos consejos sobre cómo y cuándo usar (o no usar) comentarios en tu código.

Que tantos comentarios usar

Ya has escuchado frases como “Menos es más” o “Calidad es mejor que cantidad”, pues esto funciona muy bien a la hora decidir cuantos comentarios son suficientes. Nadie quiere pasar sobre 100 líneas de comentarios antes de comenzar a ver el código del archivo.

Generalmente, un programador tiene que cumplir con tiempos de entrega, no tiene tiempo de leer comentarios extensos, repetitivos y redundantes. Por eso es mejor limitar los comentarios a aquellas cosas que no pueden ser comprendidos de otra forma.

Al inicio puede ser difícil decidir cuándo escribir un comentario y cuando no, pero en los siguientes puntos vamos a ver algunos criterios que pueden ayudarnos.

No uses comentarios para estos casos

Estos son algunos casos en los que definitivamente no debes usar comentarios, el primero es escribir datos como fechas de cambios, autor o llevar una lista de cambios, la razón es porque hoy en día se suele tener un sistema de control de versiones como GIT en donde podemos consultar toda esa información y de forma más precisa.

Esta es una captura de pantalla de un programa hecho en ABAP, como puedes ver, lleva comentarios para describir la fecha de creación, log de cambios y autores.

Ejemplo de comentario que no aporta valor en un programa

Esta es una captura de pantalla del control de versiones de WordPress, podemos ver que el archivo index.php fue modificado por esas personas y en esas fechas, también podemos navegar para ver más información sobre los cambios, entonces no es necesario que incluyas eso en los comentarios, esos comentarios podrían incluso estar desactualizados y mentirte.

Podemos obtener información sobre las modificaciones de un archivo desde GIT en lugar de hacer desde comentarios en el código fuente.

Lo segundo que debes evitar es describir el código, debes recordar que, si alguien está leyendo tus comentarios, también sabe cómo leer el código, entonces evita hacer comentarios como “Incrementar el contador en 1” o “Llamar a la función xyz”, recuerda que, si el código está bien escrito, no necesita que expliques lo que hace cada línea de código.

Algunas personas sugieren escribir en el inicio del archivo, una lista de las funciones que contiene o si se trata de una clase, incluir una lista de los métodos de la clase. El problema con esto es que pronto tendrás que agregar más funciones o métodos y la documentación hecha por comentarios se volverá obsoleta rápidamente. Además, los editores de código (IDE) modernos tiene la capacidad de listar todas las funciones o métodos de una clase.

Explica por qué, en lugar de como.

Como ya lo mencioné, si alguien lee comentarios de un programa, también sabe cómo leer código. Por eso podría ser más útil que expliques por qué haces algo, en lugar de explicar cómo lo haces. Por ejemplo, si estás leyendo información de una tabla en una base de datos, en lugar de colocar un comentario como “Leer tabla xyz”, sería más útil un comentario como “Leo la tabla xyz porque tiene únicamente los clientes en mora y no necesito los demás clientes”.

Cualquier cosa que pueda ser interpretada a través del código, no necesita ser duplicada mediante un comentario, en lugar de eso siempre intenta explicar por qué estás haciendo algo y si no necesitas explicar por qué, entonces posiblemente no necesitas agregar un comentario.

Conclusiones

No importa que seas el único programador en un proyecto o que trabajes en equipo con otros programadores, los comentarios son parte importante del código y deben ser escritos de la mejor forma posible.

Espero que alguno de estos consejos te ayude en tus proyectos y si quieres aportar algo, me encantaría que dejaras un comentario.

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *