Como sabemos por el capítulo Estructura del código, los comentarios pueden ser de una sola línea: comenzando con // y de varias líneas: /* ... */ .
Normalmente los usamos 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 suelen utilizarlos de forma errónea.
Los principiantes tienden a utilizar comentarios para explicar "lo que sucede en el código". Como esto:
// Este código hará esto (...) y aquello (...) // ...y quién sabe qué más... muy; complejo; código;
Pero en un buen código, la cantidad de comentarios “explicativos” debería ser mínima. En serio, el código debería ser fácil de entender sin ellos.
Hay una gran regla al respecto: "si el código es tan confuso que requiere un comentario, entonces tal vez debería reescribirse".
A veces es beneficioso reemplazar un fragmento de código con una función, como aquí:
función mostrarPrimes(n) {
siguientePrime:
para (sea i = 2; i < n; i++) {
//comprobar si i es un número primo
para (sea j = 2; j < i; j++) {
si (i % j == 0) continúa con nextPrime;
}
alerta(yo);
}
} La mejor variante, con una función factorizada isPrime :
función mostrarPrimes(n) {
para (sea i = 2; i < n; i++) {
si (!isPrime(i)) continúa;
alerta(yo);
}
}
la función esPrima(n) {
para (sea i = 2; i < n; i++) {
si (n % i == 0) devuelve falso;
}
devolver verdadero;
}Ahora podemos entender el código fácilmente. La función misma se convierte en el comentario. Este código se llama autodescriptivo .
Y si tenemos una “hoja de códigos” larga como esta:
// aquí agregamos whisky
para(sea i = 0; i < 10; i++) {
dejar caer = obtener whisky();
oler(gotar);
agregar(gota, vaso);
}
// aquí agregamos jugo
para(sea t = 0; t < 3; t++) {
let tomate = getTomate();
examinar(tomate);
dejar jugo = presionar(tomate);
agregar(jugo, vaso);
}
//...Entonces podría ser una mejor variante refactorizarlo en funciones como:
agregarWhisky(vaso);
agregarjugo(vaso);
función agregar whisky (contenedor) {
para(sea i = 0; i < 10; i++) {
dejar caer = obtener whisky();
//...
}
}
función agregarJugo(contenedor) {
para(sea t = 0; t < 3; t++) {
let tomate = getTomate();
//...
}
}Una vez más, las funciones mismas dicen lo que está pasando. No hay nada que comentar. Y también la estructura del código es mejor cuando se divide. Está claro qué hace cada función, qué requiere y qué devuelve.
En realidad, no podemos evitar por completo los comentarios “explicativos”. Hay algoritmos complejos. Y existen "ajustes" inteligentes con fines de optimización. Pero, en general, deberíamos intentar mantener el código simple y autodescriptivo.
Por tanto, los comentarios explicativos suelen ser malos. ¿Qué comentarios son buenos?
Describir la arquitectura
Proporcione una descripción general de alto nivel de los componentes, cómo interactúan, cuál es el flujo de control en diversas situaciones... En resumen, la vista aérea del código. Existe un lenguaje especial UML para crear diagramas de arquitectura de alto nivel que explican el código. Definitivamente vale la pena estudiarlo.
Parámetros y uso de la función del documento
Hay una sintaxis especial JSDoc para documentar una función: uso, parámetros, valor devuelto.
Por ejemplo:
/**
* Devuelve x elevado a la n-ésima potencia.
*
* @param {número} x El número a aumentar.
* @param {number} n La potencia, debe ser un número natural.
* @return {número} x elevado a la enésima potencia.
*/
función poder(x, n) {
...
}Dichos comentarios nos permiten comprender el propósito de la función y usarla de la manera correcta sin mirar su código.
Por cierto, muchos editores como WebStorm también pueden entenderlos y utilizarlos para proporcionar autocompletado y algunas comprobaciones automáticas de código.
Además, existen herramientas como JSDoc 3 que pueden generar documentación HTML a partir de los comentarios. Puede leer más información sobre JSDoc en https://jsdoc.app.
¿Por qué la tarea se resuelve de esta manera?
Lo que está escrito es importante. Pero lo que no está escrito puede ser aún más importante para entender lo que está pasando. ¿Por qué la tarea se resuelve exactamente de esta manera? El código no da respuesta.
Si hay muchas formas de resolver la tarea, ¿por qué ésta? Especialmente cuando no es el más obvio.
Sin tales comentarios es posible la siguiente situación:
Usted (o su colega) abre el código escrito hace algún tiempo y ve que es "subóptimo".
Piensas: "Qué estúpido era entonces y cuánto más inteligente soy ahora", y reescribes usando la variante "más obvia y correcta".
…La necesidad de reescribir era buena. Pero en el proceso se ve que en realidad falta la solución “más obvia”. Incluso recuerdas vagamente por qué, porque ya lo probaste hace mucho tiempo. Vuelves a la variante correcta, pero perdiste el tiempo.
Los comentarios que explican la solución son muy importantes. Ayudan a continuar el desarrollo de la manera correcta.
¿Alguna característica sutil del código? ¿Dónde se utilizan?
Si el código tiene algo sutil y contrario a la intuición, definitivamente vale la pena comentarlo.
Una señal importante de un buen desarrollador son los comentarios: su presencia e incluso su ausencia.
Los buenos comentarios nos permiten mantener bien el código, volver a él después de un retraso y utilizarlo de forma más eficaz.
Comenta esto:
Arquitectura general, vista de alto nivel.
Uso de funciones.
Soluciones importantes, especialmente cuando no son inmediatamente obvias.
Evite comentarios:
Eso dice "cómo funciona el código" y "qué hace".
Introdúzcalos sólo si es imposible hacer que el código sea tan simple y autodescriptivo que no los requiera.
Los comentarios también se utilizan para herramientas de documentación automática como JSDoc3: los leen y generan documentos HTML (o documentos en otro formato).