Don’t comment bad code. Rewrite it.

Clean Code Chapitre 4

Les gens qui commentent leur code seraient donc une mauvaise pratique ? J’étais dans le faux tout ce temps ?! C’est tendant d’être aussi binaire en faisant appel à une figure d’autorité, ici Robert C. Martin, auteur du livre Clean Code, pour affirmer sa position. Il existe selon moi une posture bien plus efficace à privilégier vous permettant d’apporter de la valeur dans votre produit, et cela, immédiatement. Ici, je vais me servir des commentaires de code comme exemple.

Améliorer son code en continue

// If we got a list of rooms to delete along with the team, remove them first
if (rooms.length) {
  rooms.forEach((room) => {
    Meteor.call('eraseRoom', room);
  });
}

L’exemple ci-dessus provient du code source pris au hasard sur le GitHub de RocketChat (fichier teams.ts). J’aime bien celui-ci parce qu’il caractérise le genre de commentaire dont je ne suis pas fan. Il explique littéralement ce que les cinq lignes suivantes font. Surtout que les plus perspicaces diront que l’on peut refactor ce bout de code en une seule ligne. C’est certain que face à ce type d’exemple, on serait tenté de se demander la pertinence de la pratique et ne plus en faire du tout.

if (Meteor.isCordova && Google.signIn) {
  // After 20 April 2017, Google OAuth login will no longer work from
  // a WebView, so Cordova apps must use Google Sign-In instead.
  // https://github.com/meteor/meteor/issues/8253
  Google.signIn(options, callback);
  return;
}

Toujours dans le même code source, nous avons ici plus de commentaires que de code. Certains affirmeront que cela alourdit la lecture, ou que cela n’a rien à faire ici et devrait se mettre dans une documentation à part.

Maintenant, j’aimerais vous poser la question suivante : quel est le point commun entre ces deux exemples ?

Ils améliorent le code. Eh oui.

Quelles que soient les raisons de la personne ayant écrit ces lignes à l’apparence barbantes, l’intention est bien d’améliorer le produit.
Les commentaires représentent un moyen très rapide et très simple d’implémentation pour passer un message, afin d’éviter les problèmes futurs. C’est d’autant plus facile à voir avec le dernier exemple.

Ensuite, il reste un moyen encore plus efficace que ceux-ci pour faire la même chose. Voilà le point que les personnes dites Crafter veulent mettre en évidence, parfois maladroitement.
La première idée en tête est d’encapsuler le bloc dans une méthode à part, dont le nom remplacerait le rôle du commentaire.

function eraseFirstRoomsAlongWithTeam() {
  if (rooms.length) {
    rooms.forEach((room) => {
      Meteor.call('eraseRoom', room);
    });
  }
}

Cette technique s’appelle l’extract method. Certains IDE vous permettent de le faire en un raccourci, dont l’efficacité reste dépendant du langage utilisé. On pourrait aller encore plus loin en suivant d’autres patterns. Cela va dépendre du temps que vous souhaitez allouer à l’amélioration de ce bout de module.

L’étape supérieure, serait de passer par un test unitaire pour encore plus verrouiller le contrôle d’un bloc qui vous paraît obscur. Une fois de plus, allez-vous prendre du temps à cela ?

On s’adresse à des humains avant tout

Cela ne vous aura pas échappé : même le plus grand des imbéciles peut écrire du code que la machine peut comprendre. Le développeur écrivant du code s’adresse en priorité à d’autres humains qui liront ce code dans le futur. Un code plus compréhensif permet une meilleure maintenance et amélioration.

Quels sont les moyens de communication qu’une personne développant une application possède ? Dans l’ordre de simplicité à mettre en place, je vois :

• par une ou plusieurs lignes de commentaire
• par une documentation externe (confluence, jira)
• par du pair programming, peer review
• par du refactoring (extract method, architecture de code claire, tests unitaires)

Les Crafters se focalisent essentiellement sur les deux derniers points, pensant que les deux premiers sont des symptômes d’une mauvaise qualité logicielle. Le pire serait d’adopter pour aucun de ces points.
Est-ce qu’une organisation ne faisant que les deux premiers ont une mauvaise qualité ? Si de base, l’entreprise fait de l’argent avec, c’est peut-être que la technique fonctionne jusque-là.

Vous avez le droit de voir beaucoup plus loin afin d’épargner de longues heures de maintenance, la fameuse dette technique. Invisible sur le court terme, très peu remboursé.

En résumé

Commenter son code n’est pas une mauvaise pratique, elle démontre une volonté d’apporter de la valeur en un minimum d’investissement. Il sera toutefois nécessaire d’aller plus loin si l’on souhaite que le produit survive dans le temps long.

En bonus, j’aimerais vous partager une conférence sur la dérive du Software Craftsmanship, et vous rappelez qu’on s’adresse à une organisation qui ne souhaite pas mettre la clé sous la porte.

Les commentaires ne sont qu’un outil parmi d’autres. Je pense en effet que leur efficacité est faible. Mais ce n’est pas une mauvaise pratique. Ne vous stressez pas pour si peu.