Documentation technique : pourquoi commenter votre code peut être contre-productif ?

Vous ouvrez un fichier legacy et tombez sur ce commentaire : "Fonction temporaire, à supprimer après le bug fix." Le commentaire date de 2019, le code est en production depuis trois ans. Cette situation vous dit quelque chose ? Félicitations, vous venez de découvrir pourquoi les commentaires sont souvent plus dangereux qu'utiles. Un code qui se documente lui-même vaut mieux que mille lignes de documentation obsolète.

Les problèmes de la documentation traditionnelle

La documentation traditionnelle pose plusieurs problèmes :

• Obsolescence inévitable : Alors que le code évolue constamment, la documentation, elle, reste souvent en retrait, créant un décalage qui peut facilement induire en erreur.
• Maintenance chronophage : La mise à jour de la documentation exige du temps et de la rigueur, souvent négligés lorsque les échéances approchent. Elle est perçue comme une tâche secondaire, avec un retour sur investissement immédiat limité pour les équipes.
• Risque accru d'erreur : Une documentation obsolète peut s'avérer plus nuisible que l'absence totale d'information. Elle risque de semer la confusion chez les nouveaux développeurs et, au final, de miner la confiance dans les informations documentées.

Exemple parlant :

Ce simple exemple montre à quel point un commentaire peut devenir trompeur, tandis que le code, lui, reflète toujours la réalité.

La solution : Faire de votre code la meilleure documentation

Un nommage explicite

Les noms sont souvent le premier outil de documentation. Ils permettent de donner un sens immédiat au code sans nécessiter d’explications supplémentaires. Prenons un exemple pour comparer deux approches de nommage :

Dans le second exemple, le nom des paramètres et de la fonction est explicite, permettant de comprendre le but du code au premier coup d'œil.

Une architecture narrative

Un code bien structuré raconte une histoire. Chaque classe ou méthode représente une étape cohérente de cette histoire. Par exemple, une classe de gestion de commandes pourrait organiser ses méthodes pour montrer chaque phase de traitement : calcul du sous-total, application des remises et ajout de la TVA.

La structure ici rend le flux de calcul clair : chaque étape est isolée, et le code devient facile à suivre, quasiment sans commentaire.

Les tests comme documentation vivante

Les tests unitaires, en plus de garantir le bon fonctionnement, servent de documentation en explicitant le comportement attendu. Ils montrent des cas d’utilisation réels et ce que le code devrait produire, ce qui aide à comprendre ses objectifs.

Les cas où la documentation reste nécessaire

Certains éléments du code nécessitent une documentation ciblée pour garantir une compréhension globale et éviter les malentendus.

• Architecture système : Les diagrammes d'architecture, les flux de données et les interactions entre services fournissent une vue d'ensemble indispensable.
• Décisions techniques ou produit : Les choix structurants et compromis importants doivent être documentés, pour conserver une trace des décisions.
• APIs publiques et configurations complexes : Les APIs externes et les paramètres de déploiement ou variables d'environnement nécessitent une documentation claire pour en garantir la bonne utilisation.
• Règles métier : Les règles métier complexes, les exceptions et les cas spéciaux doivent être documentés pour assurer une compréhension globale et éviter les malentendus.

Ce qu'il faut retenir

• La documentation traditionnelle devient obsolète inévitablement car le code évolue plus vite qu'elle ; un code bien nommé et structuré est la seule documentation qui ne ment jamais.
• Investissez dans un nommage explicite, une architecture narrative et des tests unitaires comme documentation vivante plutôt que dans des commentaires qui seront ignorés à la prochaine modification.
• Réservez la documentation écrite aux cas où elle est irremplaçable : architecture système, décisions techniques structurantes, APIs publiques et règles métier complexes.

Questions fréquentes

Faut-il supprimer tous les commentaires du code ?

Non. Les commentaires expliquant le "pourquoi" (contraintes cachées, workarounds, décisions non évidentes) restent précieux. Ce sont les commentaires décrivant le "quoi" (ce que fait le code) qui sont redondants et dangereux car ils deviennent rapidement obsolètes.

Comment rendre son code auto-documenté ?

Un nommage explicite des variables, fonctions et classes qui décrit l'intention. Une architecture narrative où chaque méthode représente une étape cohérente du flux. Et des tests unitaires qui servent de documentation vivante en décrivant le comportement attendu.

Les tests unitaires remplacent-ils la documentation ?

Ils la complètent en montrant des cas d'utilisation réels et le comportement attendu du code. Contrairement à un commentaire qui peut devenir obsolète, un test qui échoue signale immédiatement un décalage entre la documentation et la réalité.

Conclusion

Un code de qualité est la seule documentation qui ne ment jamais. Investissez dans des noms explicites, une structure claire et des tests complets. Ce code auto-explicatif vous fera économiser des heures de maintenance et de debugging.

Votre objectif ? Écrire du code si clair qu'un nouveau développeur comprend l'intention sans lire un seul commentaire. C'est le signe d'un code vraiment professionnel.