Comentar algo es básicamente una forma de que alguien juzgue o dé una perspectiva diferente de algo, ya sea en términos de bueno o malo en el proceso, consideraremos si mejoraremos en base a eso o simplemente lo ignoraremos, según los comentarios. que nos ha dado.

Pero, en esta publicación, no hablaremos sobre política, sino que es más técnico sobre desarrollo web, y mi perspectiva es por qué necesitamos hacer esto mientras escribimos nuestro código.

En nuestra discusión esta vez, veremos cuán importante es comentar una función que hemos creado nosotros mismos, por supuesto en JavaScript. Imagina que tenemos una función como esta:

function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

window.location.href = `${x}://${y}`;

¿Cuál es la explicación de los argumentos `x`y `y`? si completaremos `object`o `string`tal vez podemos completar alguna entrada especial? otro usamos Typescript, el mecanismo de datos de tipo lo realizará Typescript en tiempo de ejecución o tal vez en desarrollo , pero ¿qué tal si usamos JavaScript?

Sí, en JavaScript (JS) , el editor de IntelliSense mostrará los argumentos de la función con el significado de que se permitirá cualquier dato.`setLocation``any`

Como puede ver básicamente, aquí hay un problema de dos; Computadora y Humano , cuando la computadora lee el código continuará ejecutándose sin importar el nombre del argumento que hayamos establecido, pero ¿qué pasa con un Humano ?

La función que creamos será difícil de entender para el próximo desarrollador (Humano), porque sin saber qué enviar a la `setLocation`función, es diferente si dejamos un comentario.

// args `x` with data type string, is a protocol
// args `y` with data type string, is a domain name
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

Intentaremos comentar sobre la función que creamos, de acuerdo con el estándar de JSDoc , cambiaremos el comentario anterior a algo como esto

/**
 * A function that can be executed on address bar browser
 * @param {string} x a host url
 * @param {string} y a domain url
 */
function setLocation(x, y) {
  window.location.href = `${x}://${y}`;
}

De hecho, IntelliSense solo puede ayudar a los usuarios a determinar qué se debe enviar en esa función cuando queremos usar eso, pero no está totalmente escrito estrictamente .

Esto es muy útil, especialmente si tenemos una función en la que debemos enviar un objeto de datos como parámetro de la función, por ejemplo, tenemos una función como esta

/**
 * @param {object} fullName
 * @param {string} fullName.firstName your first name
 * @param {string} fullName.lastName your last name
 */
function overwriteData(fullName) {
  return {
    firstName: "Adib",
    lastName: "Firman",
    ...fullName
  };
}

Como de costumbre , IntelliSense nos dará una pista, y sabes que lo más interesante para este enfoque es

En la imagen de arriba, ingresaremos datos de acuerdo con las instrucciones de IntelliSense , por supuesto, obtendremos una pista de nuestro editor, interesante, ¿no es así?

La siguiente pregunta es, ¿debemos comentar todas las funciones que hemos creado? Por supuesto que no, un ejemplo de una función como esta

const sum = (firstNum, secondNum) => firstNum + secondNum;

Conclusión

Ponga algunos comentarios sobre nuestra función, dependiendo de cómo se usará, ¿los parámetros dados son muy complejos ? ¿O es legible desde la función de nomenclatura y los argumentos creados?

Pero si cree que la función necesita recibir un comentario, es mejor, porque es para que sea más fácil de mantener por parte del próximo desarrollador (humano).

Gracias.