Comentarios
Como hemos aprendido en el capítulo sobre Estructura del código, los comentarios pueden ser de una sola línea (iniciados con //) o de múltiples líneas (encerrados entre /* … */).
Generalmente, los utilizamos para describir cómo y por qué funciona el código.
A primera vista, los comentarios pueden parecer obvios, pero los principiantes en programación a menudo los utilizan incorrectamente.
Comentarios inapropiados
Los programadores novatos tienden a usar los comentarios para explicar “lo que hace el código”. Algo así:
// Este código hará esto (...) y aquello (...)
// ...y quién sabe qué más...
código;
muy;
complejo;
Sin embargo, en un buen código, la cantidad de comentarios “explicativos” debería ser mínima. En realidad, el código debería ser lo suficientemente claro como para entenderse sin necesidad de ellos.
Hay una regla fantástica al respecto: “si el código es tan poco claro que necesita un comentario, tal vez debería ser reescrito”.
Estrategia: funciones externas
A veces, es beneficioso reemplazar bloques de código con funciones, como en este ejemplo:
function showPrimes(n) {
nextPrime:
for (let i = 2; i < n; i++) {
// verificar si i es un número primo
for (let j = 2; j < i; j++) {
if (i % j == 0) continue nextPrime;
}
alert(i);
}
}
Una mejor opción sería con una función externa isPrime:
function showPrimes(n) {
for (let i = 2; i < n; i++) {
if (!isPrime(i)) continue;
alert(i);
}
}
function isPrime(n) {
for (let i = 2; i < n; i++) {
if (n % i == 0) return false;
}
return true;
}
Ahora podemos entender el código fácilmente. La propia función actúa como un comentario. Este tipo de código se llama auto-descriptivo.
Estrategia: crear funciones
Si tenemos un código largo como este:
// aquí añadimos whisky
for (let i = 0; i < 10; i++) {
let drop = getWhiskey();
smell(drop);
add(drop, glass);
}
// aquí añadimos jugo
for (let t = 0; t < 3; t++) {
let tomato = getTomato();
examine(tomato);
let juice = press(tomato);
add(juice, glass);
}
// ...
Una versión mejor sería reescribirlo en funciones de esta manera:
addWhiskey(glass);
addJuice(glass);
function addWhiskey(container) {
for (let i = 0; i < 10; i++) {
let drop = getWhiskey();
// ...
}
}
function addJuice(container) {
for (let t = 0; t < 3; t++) {
let tomato = getTomato();
// ...
}
}
De nuevo, las propias funciones nos dicen qué está pasando. No hay nada que comentar. Además, la estructura del código es mejor cuando está dividida. Queda claro qué hace cada función, qué necesita y qué retorna.
En realidad, no podemos evitar totalmente los comentarios “explicativos”. Existen algoritmos complejos y trucos ingeniosos para optimizar el código. Sin embargo, generalmente debemos intentar mantener el código simple y auto-descriptivo.
Comentarios apropiados
Entonces, los comentarios explicativos suelen ser inapropiados. ¿Qué comentarios son apropiados?
Describe la arquitectura: Proporcionan una visión general de alto nivel de los componentes, cómo interactúan y cuál es el flujo de control en diversas situaciones. En resumen, una vista panorámica del código. Hay un lenguaje de diagramas especial, UML, para diagramas de alto nivel, que vale la pena estudiar.
Documenta la utilización de una función: Hay una sintaxis especial, JSDoc, para documentar una función: uso, parámetros y valor devuelto. Por ejemplo:
/**
* Devuelve x elevado a la potencia de n.
*
* @param {number} x El número a elevar.
* @param {number} n La potencia, debe ser un número natural.
* @return {number} x elevado a la potencia de n.
*/
function pow(x, n) {
// ...
}
Este tipo de comentarios nos permite entender el propósito de la función y cómo usarla correctamente sin tener que examinar su código.
Por cierto, muchos editores como WebStorm también pueden entender estos comentarios y usarlos para proveer auto completado y algún tipo de verificación automática del código.
Además, existen herramientas como JSDoc 3 que pueden generar documentación en formato HTML a partir de los comentarios. Puedes obtener más información sobre JSDoc en jsdoc.app.
¿Por qué se resuelve de esa manera?
Lo que está escrito es importante, pero lo que no está escrito puede ser aún más importante para entender qué está pasando. ¿Por qué se resuelve la tarea de esa manera específica? El código no nos da ninguna respuesta.
Si hay muchas maneras de resolver el problema, ¿por qué esta? Especialmente cuando no es la más obvia.
Sin estos comentarios, las siguientes situaciones son posibles:
- Tú (o tu compañero) abres el código escrito hace algún tiempo y te das cuenta de que es “subóptimo”.
- Piensas: “Qué tonto era antes, y qué listo soy ahora”, y lo reescribes utilizando la variante “más obvia y correcta”.
- …El impulso de reescribir era bueno. Pero en el proceso te das cuenta de que la solución “más obvia” en realidad falla. Incluso recuerdas vagamente por qué, porque ya lo intentaste hace mucho. Vuelves a la variante correcta, pero has perdido tiempo.
Los comentarios que explican la solución correcta son muy importantes. Nos ayudan a continuar el desarrollo de forma correcta.
Características sutiles del código
Si el código tiene algo sutil y contraintuitivo, definitivamente vale la pena comentarlo.
Resumen
Una señal importante de un buen desarrollador son los comentarios: su presencia e incluso su ausencia.
Los buenos comentarios nos permiten mantener el código bien estructurado, volver después de un tiempo y usarlo de manera más efectiva.
Comenta lo siguiente:
- Arquitectura general, vista de alto nivel.
- Utilización de funciones.
- Soluciones importantes, especialmente cuando no son inmediatamente obvias.
Evita comentar lo siguiente:
- Explicaciones sobre “cómo funciona el código” y “qué hace”.
- Escríbelos solo si es imposible escribir el código de manera tan simple y auto-descriptiva que no los necesite.
Los comentarios también se utilizan para herramientas de auto documentación como JSDoc3: las leen y generan documentación en HTML (u otros formatos).
