03. JS, Comentarios¿Cómo comento dentro de mi JavaScript?

Una de las prácticas recomendadas a la hora de escribir tu código, es incluir un comentario dentro del mismo, para que en el futuro, puedas entender el porqué llegaste a esa solución.

Otra de las ventajas de este tipo de prácticas es que otros programadores podrán entender que carajo hace ese trozo de código y así poder editar o completar tu trabajo.

Por lo que puedes incluir cualquier fragmento de texto en formato comentario dentro del código de programación.

Si quiere poner un texto de una sola línea, los caracteres utilizados son dos líneas invertidas //

// Declaramos la variable text para guardar un string
text = "¡Hola mundo!";
// Y lo imprimimos por pantalla
document.write(text);

Si lo que quieres es un comentario de varias líneas, porque el texto es generoso, la forma utilizada es /* ... */

/* Declaramos la variable text para guardar un string
y lo imprimimos por pantalla */

text = "¡Hola mundo!";
document.write(text);

Hay que decir que puedes utilizar los espacios en blanco que desees, puedes hacer la estructura que te apetezca.

Incluso, en VisualStudio Code, así como otros editores, hay extensiones que te hacen formatos de comentarios personalizados y con estilos, para mi gusto, excesivos. Pero que si lo deseas se pueden utilizar sin ningún problema.

Todos los comentarios son ignorados por el interprete de código. Eso sí, tu archivo a la hora de cargar será más pesado.

Ejemplo de comentario sencillo:

/**
* Esto es un comentarios de
* varias líneas
*/

Reglas para un buen comentado

Ahora que conoces la forma de comentar el código de tu programa, sería interesante seguir una serie de reglas que te ayudarán a hacer unos comentarios más legibles.

Comentario implícito

Cuando piensas en el nombre de tus clases o funciones debes poner el nombre lo más descriptivo posible. De esa forma, no hace falta incluir comentarios explícitos si la clase o función es sencilla.

Por ejemplo, si quieres hacer un función que calcule la raíz cuadrada de un número.

function Numero1() {
...
}

function CalcularRaiz(){
...
}

Siempre será mejor que optes por el segundo nombre porque es más representativo que el primero. En el primer ejemplo, tendrás que añadir un comentario para explicar qué hace la función. En cambio, en el segundo ejemplo, podrías prescindir de dicho comentario, ya que el objetivo de la función está implícito dentro del nombre.

Para que aumentes mucho más la legibilidad, lo ideal seria que el nombre de las funciones las hagas en inglés, así ampliarás el número de programadores que entenderán tu código.

Comentarios regulares

Normalmente cuando estés trabajando en un proyecto, debes utilizar un estilo de comentarios regular. Es decir, usando el mismo estilo en todas las partes del proyecto.

Por otro lado, si heredas un proyecto de otro programador o realizas un mantenimiento que no has implementado, tendrías que conservar el estilo que ese programador ha utilizado, para que de ese modo la uniformidad del proyecto se mantenga. Otra opción sería cambiarlo todo, pero eso sería una locura, ¿Verdad?

Comentarios multilínea en funciones

Es recomendable que utilices comentarios multilínea en las cabeceras de las funciones, ya que así podrás exponer las consideraciones previas, explicar los parámetros que recibe la función, el autor, constantes, etc., en definitiva, contra más documentada este, mejor. En cambio, los comentarios simples los puedes implementar en una sola línea.

Un ejemplo sería el siguiente:

/**
* @author Raül Bocache
* @param {number}
* …
*
*/

Comentar cada archivo .js al principio

Cuando se participa en un gran proyecto suelen haber decenas de archivos diferentes. Es una buena práctica que añadas a cada archivo .js una cabecera de comentarios donde incluyas textos descriptivos de lo que contiene el archivo, además de datos relevantes para futuras revisiones.

Sólo hay que pensar una cosa, contra más comentarios haya en un archivo, posteriormente, más fácil te resultará su mantenimiento.

Utiliza etiquetas normalizadas

Utilizar etiquetas normalizadas hace que tu código sea más legible para otros programadores, incluso de otros países. Por eso es muy recomendable que las utilices.

A continuación, en la tabla, tienes una serie de etiquetas normalizadas:

Hay muchas más etiquetas normalizadas, aquí sólo hay una pequeña muestra de ellas.