Commentaires
Thèse : Tout doit être standardisé. Il suffit de définir LA bonne manière pour chaque chose. De cette manière on évite les discussions et les conflits d'idées.
Antithèse : Rien ne doit être standardisé. Chacun fait selon ses critères et ses préférences. De cette manière on évite les discussions et les conflits d'idées.
Synthèse : Une équipe établit parallèlement au logiciel qu'elle développe, un état de l'art définissant la meilleure façon de faire étant donnés son contexte, ses objectifs et ses contraintes. Les discussions et conflits d'idées sont incontournables si elle veut améliorer cet état de l'art.
🗺️🪜🧯
Prenons comme exemple les commentaires sur le code, un sujet qui comme la position des accolades ou l'espacement vertical, suscitent des débats animés à proportion inverse des enjeux, ayant plus d'impact sur les lecteurs du code que sur le comportement de celui-ci à l'exécution.
Pendant longtemps, la règle la plus courante a été de commenter le code, afin de le rendre plus compréhensible. J'ai eu l'occasion de travailler dans des environnements où le "taux de commentaire" était systématiquement mesuré. Qui dit mesurer dit surveiller. Qui dit surveiller dit maquiller. Dans certain cas — dans certains cas seulement — la règle des commentaires contribuait à d'absurdes initiatives de mise en conformité.
Avec la popularisation grandissante du refactoring et des "code smells" les commentaires sont presques devenus un "anti-pattern" : le commentaire est un déodorant apposé sur un code smell. D'où :
Ne commentez pas le code, réparez le.
Ce pattern, allié à d'autres tels que "Intention Revealing Names", "Extract Method", etc. fait reposer la maintenabilité du code principalement sur le code lui même ! (Une idée apparemment simple qui n'aurait pas marché du temps où l'on codait principalement en assembleur 😉)
Au détour d'une discussion récente avec des collègues, j'ai pu réaliser qu'aucune de ces deux règles : "Commentez votre code" et "Ne commentez pas le code, réparez-le" ne peut fonctionner de manière absolue. La première fait le présupposé que tout code quelqu'il soit manque de clarté. La seconde suggère que le code qui manque de clarté devrait être interdit, et réparé séance tenante par l'équipe, à qui son état de l'art dicte la perfection, rien de moins.
La règle qui fonctionnerait à mon sens, et qu'une équipe pourrait facilement intégrer à son état de l'art, la voici :
Commentez le code que vous ne pouvez pas réparer
Exemples :
// variable globale posée à des fins de test
// agencement
…
// action
…
// assertion
Le but d'un état de l'art n'est pas d'inscrire le projet dans le ciel abstrait des Lois du Génie Logiciel, mais d'aider l'équipe à progresser dans sa manière de résoudre un problème posé dans un contexte et des objectifs donné à un instant t.
Stay Tuned !