Comme nous le savons grâce au chapitre Structure du code, les commentaires peuvent être sur une seule ligne : commençant par // et multilignes : /* ... */ .
Nous les utilisons normalement pour décrire comment et pourquoi le code fonctionne.
À première vue, les commentaires peuvent paraître évidents, mais les novices en programmation les utilisent souvent à tort.
Les novices ont tendance à utiliser des commentaires pour expliquer « ce qui se passe dans le code ». Comme ça:
// Ce code fera telle chose (...) et cette chose (...) // ...et qui sait quoi d'autre... très; complexe; code;
Mais dans un bon code, la quantité de ces commentaires « explicatifs » devrait être minime. Sérieusement, le code devrait être facile à comprendre sans eux.
Il existe une excellente règle à ce sujet : « si le code est si peu clair qu'il nécessite un commentaire, alors peut-être devrait-il être réécrit à la place ».
Parfois, il est avantageux de remplacer un morceau de code par une fonction, comme ici :
fonction showPrimes(n) {
suivantPrime :
pour (soit i = 2; i < n; i++) {
// vérifie si i est un nombre premier
pour (soit j = 2; j < i; j++) {
si (i % j == 0) continue nextPrime ;
}
alerte(i);
}
} La meilleure variante, avec une fonction factorisée isPrime :
fonction showPrimes(n) {
pour (soit i = 2; i < n; i++) {
if (!isPrime(i)) continue ;
alerte(i);
}
}
la fonction estPrime(n) {
pour (soit i = 2; i < n; i++) {
if (n % i == 0) renvoie false ;
}
renvoie vrai ;
}Nous pouvons maintenant comprendre facilement le code. La fonction elle-même devient le commentaire. Un tel code est appelé auto-descriptif .
Et si nous avons une longue « feuille de codes » comme celle-ci :
// ici on ajoute du whisky
pour(soit i = 0; i < 10; i++) {
laisser tomber = getWhiskey();
odeur(goutte);
ajouter(goutte, verre);
}
// ici on ajoute du jus
pour(soit t = 0; t < 3; t++) {
laissez tomate = getTomato();
examiner(tomate);
laisser jus = presser (tomate);
ajouter(jus, verre);
}
//...Ensuite, il pourrait être une meilleure variante de le refactoriser en fonctions telles que :
addWhisky(verre);
addJuice(verre);
function addWhiskey (conteneur) {
pour(soit i = 0; i < 10; i++) {
laisser tomber = getWhiskey();
//...
}
}
fonction addJuice (conteneur) {
pour(soit t = 0; t < 3; t++) {
laissez tomate = getTomato();
//...
}
}Encore une fois, les fonctions elles-mêmes disent ce qui se passe. Il n'y a rien à commenter. Et la structure du code est également meilleure lorsqu'elle est divisée. Il est clair ce que fait chaque fonction, ce qu'elle prend et ce qu'elle renvoie.
En réalité, on ne peut pas totalement éviter les commentaires « explicatifs ». Il existe des algorithmes complexes. Et il existe des « ajustements » intelligents à des fins d’optimisation. Mais en général, nous devrions essayer de garder le code simple et auto-descriptif.
Ainsi, les commentaires explicatifs sont généralement mauvais. Quels commentaires sont bons ?
Décrire l'architecture
Fournissez un aperçu de haut niveau des composants, de la façon dont ils interagissent, quel est le flux de contrôle dans diverses situations… En bref – une vue d'ensemble du code. Il existe un langage spécial UML pour créer des diagrammes d'architecture de haut niveau expliquant le code. Cela vaut vraiment la peine d'être étudié.
Paramètres et utilisation de la fonction de document
Il existe une syntaxe spéciale JSDoc pour documenter une fonction : utilisation, paramètres, valeur renvoyée.
Par exemple:
/**
* Renvoie x élevé à la puissance n.
*
* @param {number} x Le nombre à augmenter.
* @param {number} n La puissance doit être un nombre naturel.
* @return {number} x élevé à la nième puissance.
*/
fonction pow(x, n) {
...
}De tels commentaires nous permettent de comprendre le but de la fonction et de l'utiliser correctement sans regarder dans son code.
À propos, de nombreux éditeurs comme WebStorm peuvent également les comprendre et les utiliser pour fournir une saisie semi-automatique et une vérification automatique du code.
Il existe également des outils comme JSDoc 3 qui peuvent générer une documentation HTML à partir des commentaires. Vous pouvez lire plus d'informations sur JSDoc sur https://jsdoc.app.
Pourquoi la tâche est-elle résolue de cette façon ?
Ce qui est écrit est important. Mais ce qui n’est pas écrit est peut-être encore plus important pour comprendre ce qui se passe. Pourquoi la tâche est-elle résolue exactement de cette façon ? Le code ne donne aucune réponse.
S’il existe de nombreuses façons de résoudre le problème, pourquoi celle-ci ? Surtout quand ce n’est pas le plus évident.
Sans ces commentaires, la situation suivante est possible :
Vous (ou votre collègue) ouvrez le code écrit il y a quelque temps et constatez qu'il est « sous-optimal ».
Vous pensez : « Comme j'étais stupide à l'époque, et combien je suis plus intelligent maintenant » et réécrivez en utilisant la variante « plus évidente et plus correcte ».
… L’envie de réécrire était bonne. Mais ce faisant, vous constatez que la solution « la plus évidente » fait réellement défaut. Vous vous souvenez même vaguement pourquoi, car vous l'avez déjà essayé il y a longtemps. Vous revenez à la bonne variante, mais vous avez perdu du temps.
Les commentaires qui expliquent la solution sont très importants. Ils contribuent à poursuivre le développement de la bonne manière.
Des fonctionnalités subtiles du code ? Où sont-ils utilisés ?
Si le code contient quelque chose de subtil et de contre-intuitif, cela vaut vraiment la peine de le commenter.
Un signe important d'un bon développeur sont les commentaires : leur présence et même leur absence.
Les bons commentaires nous permettent de bien maintenir le code, d'y revenir après un certain temps et de l'utiliser plus efficacement.
Commentez ceci :
Architecture globale, vue de haut niveau.
Utilisation des fonctions.
Des solutions importantes, surtout lorsqu’elles ne sont pas immédiatement évidentes.
Évitez les commentaires :
Cela indique « comment le code fonctionne » et « ce qu'il fait ».
Insérez-les uniquement s'il est impossible de rendre le code si simple et auto-descriptif qu'il ne les nécessite pas.
Les commentaires sont également utilisés pour les outils d'auto-documentation comme JSDoc3 : ils les lisent et génèrent des documents HTML (ou des documents dans un autre format).