Commentaires

Comme nous le savons du chapitre Structure du code, les commentaires peuvent tre simples : partir de // et multiligne : /* ... */.

Nous les utilisons normalement pour dcrire comment et pourquoi le code fonctionne.

De prime abord, les commentaires peuvent sembler vidents, mais les novices en programmation les utilisent souvent tort.

Mauvais commentaires

Les novices ont tendance utiliser des commentaires pour expliquer ce qui se passe dans le code. Comme ceci :

// Ce code fera cette chose (...) et cette chose (...)
// ...Et qui sait quoi d'autre...
very;
complex;
code;

Mais en bon code, le nombre de ces commentaires explicatifs devrait tre minime. Srieusement, le code devrait tre facile comprendre sans eux.

Il existe une excellente rgle ce sujet: Si le code est si peu clair quil ncessite un commentaire, il devrait peut-tre tre rcrit.

Recette: refactoriser les fonctions

Parfois, il est avantageux de remplacer un code par une fonction, comme ici :

function showPrimes(n) {
  nextPrime:
  for (let i = 2; i < n; i++) {

    // check if i is a prime number
    for (let j = 2; j < i; j++) {
      if (i % j == 0) continue nextPrime;
    }

    alert(i);
  }
}

La meilleure variante, avec une fonction factorise est 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;
}

Maintenant, nous pouvons comprendre le code facilement. La fonction elle-mme devient le commentaire. Un tel code est appel auto-descriptif.

Recette: crer des fonctions

Et si nous avons une longue feuille de code comme celle-ci :

// ici on ajoute du whisky
for(let i = 0; i < 10; i++) {
  let drop = getWhiskey();
  smell(drop);
  add(drop, glass);
}

// ici on ajoute du jus
for(let t = 0; t < 3; t++) {
  let tomato = getTomato();
  examine(tomato);
  let juice = press(tomato);
  add(juice, glass);
}

// ...

Ce pourrait tre une meilleure variante de le refactoriser dans des fonctions comme :

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();
    //...
  }
}

Une fois encore, les fonctions elles-mmes racontent ce qui se passe. Il ny a rien commenter. Et aussi la structure du code est meilleure quand elle est divise. Cest clair ce que chaque fonction fait, ce quelle ncessite et ce quelle renvoie.

En ralit, nous ne pouvons pas totalement viter les commentaires explicatifs. Il existe des algorithmes complexes. Et il existe des rglages intelligents des fins doptimisation. Mais gnralement, nous devrions essayer de garder le code simple et auto-descriptif.

Bons commentaires

Ainsi, les commentaires explicatifs sont gnralement mauvais. Quels commentaires sont bons ?

Dcrivez larchitecture

Fournissez une vue densemble des composants, de leurs interactions, de ce que sont les flux de contrle dans diverses situations En bref une vue plongeante du code. Il existe un langage spcial UML pour les diagrammes darchitecture de haut niveau. a vaut vraiment la peine de ltudier.

Documenter les paramtres de fonction et leur utilisation

Il y a une syntaxe spciale JSDoc pour documenter une fonction : utilisation, paramtres, valeur renvoye.

Par exemple :

/**
 * Renvoie x lev  la n-ime puissance.
 *
 * @param {number} x Le nombre  augmenter.
 * @param {number} n L'exposant doit tre un nombre naturel.
 * @return {number} x lev  la n-me puissance.
 */
function pow(x, n) {
  ...
}

De tels commentaires nous permettent de comprendre le but de la fonction et de lutiliser correctement sans regarder dans son code.

ce propos, de nombreux diteurs comme WebStorm peut aussi les comprendre et les utiliser pour fournir une autocompltion et une vrification automatique du code.

En outre, il existe des outils comme JSDoc 3 qui peut gnrer une documentation HTML partir des commentaires. Vous pouvez lire plus dinformations sur JSDoc ladresse http://usejsdoc.org/.

Pourquoi la tche est-elle rsolue de cette faon ?

Ce qui est crit est important. Mais ce qui nest pas crit peut tre encore plus important pour comprendre ce qui se passe. Pourquoi la tche est-elle rsolue exactement de cette faon ? Le code ne donne pas de rponse.

Sil y a plusieurs faons de rsoudre la tche, pourquoi celle-ci ? Surtout quand ce nest pas la plus vidente.

Sans ces commentaires, la situation suivante est possible :

1. Vous (ou votre collgue) ouvrez le code crit il y a quelque temps et constatez quil nest pas optimal.
2. Vous pensez: quel point jtais bte ce moment-l et quel point je suis plus malin maintenant, puis rcrivez en utilisant la variante plus vidente et correcte.
3. Lenvie de rcrire tait bonne. Mais dans le processus, vous constatez que la solution plus vidente fait dfaut. Vous vous rappelez mme vaguement pourquoi, parce que vous lavez dj essay il y a longtemps. Vous revenez la bonne variante, mais le temps a t perdu.

Les commentaires qui expliquent la solution sont trs importants. Ils aident continuer le dveloppement de la bonne faon.

Les caractristiques subtiles du code ? O sont-elles utiliss ?

Si le code a quelque chose de subtil et de contre-intuitif, cela vaut vraiment la peine de le commenter.

Rsum

Les commentaires sont une caractristique importante du bon dveloppeur : leur prsence et mme leur absence.

Les bons commentaires nous permettent de bien maintenir le code, dy revenir aprs un dlai et de lutiliser plus efficacement.

Commentez ceci :

• Architecture globale, vue de haut niveau.
• Utilisation de la fonction.
• Les solutions importantes, surtout lorsquelles ne sont pas immdiatement videntes.

vitez les commentaires :

• Qui disent comment fonctionne le code et ce quil fait.
• Ne les mettez que sil est impossible de rendre le code aussi simple et auto-descriptif quil nen ncessite pas.

Les commentaires sont galement utiliss pour les outils de documentation automatique tels que JSDoc3. Ils les lisent et gnrent des documents HTML (ou des documents dans un autre format).