Commenter quelque chose est essentiellement un moyen pour quelqu'un de juger ou de donner une perspective différente de quelque chose, que ce soit en termes de bien ou de mal dans le processus, nous déterminerons si nous allons nous améliorer en fonction de cela ou simplement l'ignorer, selon les commentaires celle qui nous est donnée.

Mais, dans cet article, nous ne parlerons pas de politique, mais c'est plus technique sur le développement Web, et mon point de vue est pourquoi nous devons le faire pendant que nous écrivons notre code.

Dans notre discussion cette fois, nous verrons à quel point il est important de commenter une fonction que nous avons nous-même créée, bien sûr en JavaScript. Imaginons que nous ayons une fonction comme celle-ci :

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

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

Quelle est l'explication des arguments `x`et `y`? si nous allons remplir `object`ou `string`ou peut-être pouvons-nous remplir une entrée spéciale ? un autre, nous utilisons Typescript, le mécanisme de données de type sera effectué par Typescript lui-même lors de l' exécution ou peut-être lors du développement , mais que diriez-vous d'utiliser JavaScript ?

Oui, en JavaScript (JS), les arguments de `setLocation`la fonction seront affichés par l' éditeur IntelliSense, ce qui signifie que `any`toutes les données seront autorisées.

Comme vous pouvez le voir fondamentalement, il y a un problème de deux ici; Computer et un Human , lorsque l'ordinateur lit le code, il continuera à s'exécuter quel que soit le nom de l'argument que nous avons défini, mais qu'en est-il d'un Human ?

La fonction que nous créons sera difficile à comprendre pour le prochain développeur (Humain), car sans savoir quoi envoyer à la `setLocation`fonction, c'est différent si on laisse un commentaire

// 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}`;
}

Nous allons essayer de commenter la fonction que nous avons créée, selon la norme de JSDoc , nous allons changer le commentaire ci-dessus en quelque chose comme ça

/**
 * 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}`;
}

En effet, IntelliSense peut simplement aider les utilisateurs à déterminer ce qui doit être envoyé dans cette fonction lorsque nous voulons l'utiliser, mais ce n'est pas totalement typé strict

Ceci est très utile, surtout si nous avons une fonction où nous devons envoyer un objet de données en tant que paramètre de la fonction, par exemple, nous avons une fonction comme celle-ci

/**
 * @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
  };
}

Comme d'habitude IntelliSense nous donnera un indice, et vous savez que le plus intéressant pour cette approche est

Dans l'image ci-dessus, nous saisirons les données conformément aux instructions d' IntelliSense , bien sûr, nous obtiendrons un indice de notre éditeur, intéressant, n'est-ce pas ?

La question suivante est, devrions-nous commenter toutes les fonctions que nous avons créées ? Bien sûr que non, un exemple d'une fonction comme celle-ci

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

Conclusion

Mettez quelques commentaires sur notre fonction, selon la façon dont elle sera utilisée, les paramètres donnés sont-ils très complexes ? ou est-il lisible à partir de la fonction de nommage et des arguments créés ?

Mais si vous estimez que la fonction doit être commentée, c'est mieux, car c'est pour faciliter sa maintenance par le prochain développeur (Humain).

Merci.