Blog Arolla

Commentaires sur les commentaires

Lorsqu’on vous a parlé de qualité de code, on vous a sûrement déjà parlé des commentaires. On vous a peut-être dit qu’il était important d’avoir du code bien commenté, voire abondamment commenté.

Alors vous ouvrez votre IDE, vous le configurez aux petits oignons et vous commencez à comm…

Minute !

Tous les commentaires ne sont pas nés égaux. En fait le code source de la plupart des applications est encombré de commentaires parfaitement inutiles et il en découle que des commentaires en quantité ne signifient pas que le code est correctement documenté.

Il existe de nombreux types de commentaires néfastes, mais il y en a deux qui en constituent la grande majorité : les radoteurs et les menteurs.

Les premiers se reconnaissent immédiatement :

Souvent générés automatiquement, ces commentaires n’apportent strictement aucune information. A bannir, donc.

Les menteurs quant à eux posent un autre problème :

Rien ne vous choque ? Il a y contradiction entre le code et le commentaire. Écrire des commentaires a un prix, ils doivent être maintenus pour rester cohérents avec le code. C’est pour cette raison qu’on ne doit commenter du code que lorsque c’est indispensable à sa compréhension.

Informer sans commenter

Le point clé pour ne pas avoir à écrire des commentaires qui risquent de devenir obsolètes, c’est d’écrire du code qui s’explique tout seul. Cela veut dire exprimer clairement ses intentions au travers du code.

Le choix des noms dans le code est primordial car ils portent la plus grande part de l’information sur l’intention du développeur.

Les noms de classes, de fonctions et de variables doivent avoir du sens, être clairs et sans ambiguïté. Idéalement, on cherchera à avoir des noms prononçables et concis.

Voici deux fonctions qui font exactement la même chose, néanmoins la seconde est compréhensible sans qu’il n’y ait besoin d’explications supplémentaires.

Il est également recommandé de maintenir une certaine cohérence pour les noms au travers de l’application, ce qui renforce la compréhension. On veillera par exemple à utiliser les verbes (de type “fetch”, “get”, “delete”, “update”) de la même façon dans tout le code.

Améliorer la structure

Pour rendre plus explicite un programme, on peut jouer sur une autre dimension et faire émerger des noms dans le code par refactoring : extraction d’expression dans des variables locales, extraction de code dans de nouvelles méthodes ou de nouvelles classes sont autant d’occasions de mettre un nom explicite sur une portion de code.

Cette technique permet d’expliquer simplement des expressions régulières (souvent cryptiques pour qui n’a pas l’habitude) ou des expressions booléennes complexes :

Ce travail est applicable à toutes les échelles de l’application et peut donc être appliqué sur des portions très locales, dans une perspective d’amélioration d’un existant. Faire l’effort de donner un nom à un concept oblige à réfléchir à sa cohérence et sa bonne formalisation : lorsqu’il est difficile de trouver un nom, c’est en général signe d’un problème dans la conception (le cas est criant pour les classes et permet de détecter rapidement les violations du Single Responsibility Principle)

Un peu d’amour quand même

Si minimiser la part des commentaires dans son application est avisé, il ne s’agit pas pour autant de les éradiquer. Ils restent un outil indispensable au développeur.

Ils permettent de fournir de l’information “hors code” (prévenir qu’un test unitaire est très long à exécuter), placer des marqueurs à destination du développeur (TODO, FIXME, à utiliser avec parcimonie) et parfois de clarifier un peu plus l’intention, comme par exemple de dire quel algorithme a été utilisé.

Par ailleurs, dès lors que l’on travaille sur une API publique, une bonne documentation via commentaires (javadoc notamment) est indispensable.

En attendant, n’oubliez jamais, le code est écrit pour être lu !

5 comments for “Commentaires sur les commentaires

  1. 14 janvier 2013 at 12 h 42 min

    Effectivement, je suis d’accord avec cette approche. Ce qui est amusant, c’est que ça vient en contradiction avec ce qu’on apprend à l’école/université…

    Ce que tu défends me rappelle le point de vue de l’auteur du livre Clean Code. Est-ce un hasard?

    Pour info, j’ai écrit un article sur ce livre:
    http://www.ghusse.com/informatique/code/clean-code_2000/

  2. 14 janvier 2013 at 18 h 17 min

    Dans ma boite, on a une autre approche concernant les commentaires “inutiles”, du type de ceux qu’on rencontre sur les getters/setters :

    On documente ces accesseurs car la méthode est amenée à évoluer et à devenir plus qu’un simple accesseur.
    Ou d’autres méthodes proches sont susceptible d’apparaître, et l’absence de commentaire sur l’accesseur “simple” sera alors manquant.

    Par exemple, on démarre avec un simple getId(), puis arrive un getLongId() ou un getShortId(), et là, si on va bien mettre un commentaire à la nouvelle fonction, on va souvent omettre d’un remettre un sur l’accesseur simple. Or il est devenu nécessaire, pour savoir différencier normal et short/long Id 🙂

  3. Houssam
    15 janvier 2013 at 10 h 04 min

    Pour moi, les #todo, #fixme sont des tags et non pas de commentaires que nous utiliserons quand la fonctionnalité que nous développons n’est pas encore “Done”. Ces tags devraient disparaître aussitôt que la fonctionnalité passe en “Done”.

    Pour la documentation, à la place des commentaires des tests unitaires peuvent être beaucoup plus utiles pour montrer comment les méthodes peuvent être utilisés. Au moins avec les tests, il n’y a pas de risque de se retrouver avec des commentaires obsolètes ou qui ne sont pas mis à jour

  4. christophe michel
    15 janvier 2013 at 10 h 49 min

    La proximité de point de vue avec les préconisations de Clean Code n’est pas un hasard, c’est un ouvrage dont j’ai beaucoup appris, ce qui a fini par transparaître dans l’article.

    Je n’ai pas pensé à le mentionner dans l’article, mais la lecture d’un article de Jeff Atwood, Coding Without Comments m’a aussi orienté vers ce type de pratiques il y a quelques années.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *