Dans les questions de qualité de développement, il y a des notions difficiles à faire passer et à contrôler. Tout ce qui concerne la documentation du code en fait parti. Si le principe de ce qui doit être dans les parties générant une documentation (Javadoc, Docstrings) et les commentaires au sein du code est généralement comprise, la pertinence de ce commentaire est plus discutable. Je suis tombé sur un bout de code intéressant pour l’illustration de la réflexion que devrait avoir un développeur autour de sa documentation. Exemple aussi intéressant qu’il est simple.

Le contexte.

Posons d’abord le contexte. Le langage est Python. La partie intéressante concerne un tableau de longueur non nulle. Le bout de code est le suivant :

if sometest:
    dosomething()
else:
    # just remove the last column
    lineArray = lineArray[:6]

Ce qui va nous intéresser, ce sont les lignes 4 et 5.

Commentaire et compréhension du code.

Si on se réfère aux principes des bonnes pratiques liées aux commentaires, un commentaire au sein du code doit expliquer pourquoi et ne doit pas générer du bruit en expliquant une évidence. D’après Clean Code de Robert C. Martin, il ne doit pas créer de confusion. Ici, la variable est allouée avec les 6 premières colonnes d’elle même, rien ne permet de déduire qu’on ne retire que la dernière colonne (il faut se rappeler que nous sommes dans un contexte d’exemple et que la définition n’est pas visible en lisant ce code). Mais est-ce important ? Quelle est la valeur ajoutée de commenter une ligne qui retient les 6 premières colonnes par on retire la dernière colonne ?

Et bien, nous allons voir cela avec un peu de refactoring de l’ensemble.

Interprétation du code.

Nous parlons de langages informatique, c’est donc bien que chaque ligne a une signification. Celle présentée ici est bien « allouer les 6 premiers éléments de la liste ». Pourtant, l’intention exprimée par le commentaire est plutôt « allouer les éléments de la liste sauf le dernier ». Il est possible d’écrire ça en Python et le code deviendrait

if sometest:
    dosomething()
else:
    # just remove the last column
    lineArray = lineArray[:-1]

Toute la différence est entre ce 6 et -1 dans la ligne 5. Python accepte des valeurs négatives pour les bornes de tableaux qui partent donc de la fin du tableau. Cela permet donc de différencier dans le code ces deux signification pour la même réalisation : prendre les six premières ou prendre tout sauf la dernière.

Retour sur le commentaire.

Si nous avons réussi à exprimer au sein du code notre intention, quelle est maintenant la pertinence du commentaire ? Il est claire qu’il est redondant et n’apporte aucune autre information par rapport à celle qu’exprime déjà le code. Un tel commentaire ne devrait pas rester au sein de votre code car ce n’est que du bruit. Les développeurs ayant plus tendance à apporter un soin à la maintenance du code et pas beaucoup à la documentation, il est préférable de limiter les commentais au minimum vital. Le code devient donc :

if sometest:
    dosomething()
else:
    lineArray = lineArray[:-1]

Et parle de lui même.

Ainsi, on peut voir qu’en Python, pour ce cas, il est possible de laisser le code exprimer notre intention. Une phrase en langage naturel est inutile.

Un exemple d’une bonne démarche ?

Presque. Cet exemple à réellement été rencontré, et la démarche à été appliquée à une étape près. Il manque dans cette présentation une étape fondamentale : vérifier quelle a été l’intention réelle du développeur. En effet, on reproche souvent à la documentation, donc aux commentaires, de ne pas être en phase avec le code. Car dans cet exemple, si on peut s’assurer que le tableau lineArray aura bien toujours dans ce bloc 7 éléments, on peut apporter cette modification. Si on ne peut pas se l’assurer, dans un cas où par exemple lineArray serait un paramètre passé à une fonction, alors tout dépend de ce qui est attendu en retour. Si c’est un tableau de 6 éléments, alors on ne doit pas changer le code mais supprimer le commentaire qui prête à confusion.

Ce commentaire n’apporte rien dans aucun des cas. Dans le premier (le tableau en entrée aura toujours 7 éléments), il n’apporte que du bruit. Retirer le dernier élément signifie garder les 6 premiers. C’est bien ce que fait le code, mais le commentaire induit une confusion nécessitant au développeur chargé de la relecture d’aller vérifier quel type de paramètre est effectivement passé. Dans le second, on serait dans une situation où le code aurai évolué mais pas le commentaire. Un développeur précédent aurai ajouté des colonnes au tableau en entrée, le comportement répondant toujours aux attentes, il n’aurai pas été nécessaire de revoir cette partie et ce commentaire reste même si il indique quelque chose de faux.

Ce qu’il faut en retenir

En premier lieu, ne commentez que ce qui est nécessaire. Le commentaire doit apporter une valeur ajoutée non présente dans le code. N’entrainez pas une confusion chez le lecteur de votre code. Ayez pour priorité de laisser votre code se faire comprendre de lui même plutôt que de rajouter un commentaire en langage naturel. Un code se vérifie, un commentaire beaucoup moins. Dans le cas présent, si vous étiez le premier auteur et si votre intention était de supprimer la dernière colonne, préférez l’écriture proposée ici. Mais en absence de test de la longueur de la liste, vous n’êtes pas à l’abris qu’une liste plus grande soit passée, donc si le retour doit être limité à 6 colonnes, l’écriture proposée ici est le mauvais choix. Enfin, pensez à ajouter des tests unitaires, de non-régression. Eux plus qu’un commentaire exprimeront ce qui est attendu et seront à jour au fur et à mesure des refactoring.