Qu’est-ce que la documentation du code ?

La documentation du code sert de carte à celles et ceux qui interagissent avec une base de code : elle les aide à comprendre ce que fait chaque élément de code, comment il fonctionne, comment l’utiliser et comment tous les éléments s’articulent entre eux. Documenter le code aide les équipes de développement à mieux maintenir le code source, tout en guidant les autres parties prenantes susceptibles de devoir comprendre et manipuler le code, comme les analystes cybersécurité, les data scientists, les ingénieurs DevOps, les product managers, les chefs de projet, les ingénieurs QA et les rédacteurs techniques.

L’approche documentation as code, ou « docs as code », traite la documentation comme du code logiciel. Cette approche gère la documentation avec les mêmes outils que le code source, notamment des systèmes de contrôle de version pour relire et suivre les modifications, des tests automatisés pour identifier les problèmes de mise en forme et de style, ainsi que l’intégration continue et la livraison continue (CI/CD) pour mettre à jour et déployer la documentation.

Alors que la documentation du code couvre la pratique plus large consistant à documenter le code, le docs as code est une stratégie spécifique et une approche plus technique de la rédaction documentaire.

La structure de la documentation du code dépend du public visé et de l’usage prévu. Voici quelques types courants de documentation :

• Documentation de bas niveau
  
  
• Documentation de haut niveau
  
  
• Documentation interne
  
  
• Documentation externe

La documentation de bas niveau désigne généralement les commentaires intégrés au code. Comptant parmi les méthodes les plus élémentaires pour rédiger de la documentation, ces annotations expliquent des lignes ou des blocs de code précis.

Les chaînes de documentation, ou docstrings, constituent une autre technique de documentation de bas niveau. Elles apparaissent avant la définition d’une classe, d’une fonction, d’une méthode ou d’un module. Les docstrings suivent un format structuré qui précise l’objectif, des exemples d’utilisation, les fonctionnalités, les paramètres et les valeurs de retour.

Les commentaires intégrés sont plus adaptés pour préciser une logique qui ne peut pas être déduite du seul examen du code, ou pour documenter du code reposant sur des algorithmes plus complexes. Les docstrings, quant à elles, peuvent être extraites pour générer de la documentation d’interface de programmation d’application (API) et fournir une aide contextuelle dans les environnements de développement intégrés (IDE).

Contrairement à la documentation de bas niveau, qui décrit des portions de code comme des éléments isolés, la documentation de haut niveau détaille leur rôle dans le workflow architectural global. Ce type de documentation logicielle comprend des organigrammes et des diagrammes UML (Unified Modeling Language) qui illustrent l’architecture du code, des documents de conception qui décrivent la logique métier et l’alignement du code avec les exigences produit, ainsi que des spécifications relatives à la structure des bases de code ou des référentiels de code.

Cette documentation technique est destinée à un usage interne au sein de l’entreprise. Elle comprend par exemple les conventions et standards de codage, ainsi que les documents de processus qui expliquent comment les équipes développent les logiciels. Les guides de configuration des environnements de développement relèvent également de la documentation interne.

Cette documentation destinée aux utilisateurs s’adresse aux développeurs et aux autres utilisateurs extérieurs à l’entreprise. Par exemple, la documentation d’API présente les classes, fonctions, méthodes et modules disponibles dans les API publiques d’un projet logiciel. La documentation externe peut également comprendre des fichiers de configuration, des notes d’intégration et un fichier README.

Le fichier README est rédigé en Markdown, un langage de balisage léger permettant de mettre en forme du texte brut. Il contient des informations sur les fonctionnalités du projet, les dépendances, les instructions d’installation, les commandes de l’interface en ligne de commande (CLI), ainsi que les options permettant d’obtenir de l’aide et du support. Les projets open source ajoutent également des informations de licence et des consignes destinées aux contributeurs pour soumettre des pull requests afin de fusionner des correctifs de bugs ou des modifications de code dans la branche principale du référentiel de code.

Écrire un code propre et clair peut déjà constituer une forme de documentation. Une bonne documentation reste toutefois essentielle et offre les avantages suivants :

• Renforcer la collaboration

• Améliorer la maintenabilité

• Accélérer le développement logiciel

• Simplifier l’intégration

Un code bien documenté favorise une meilleure collaboration et une meilleure communication au sein des équipes de développement. Les membres de l’équipe peuvent utiliser la documentation du code comme langage commun pour mener des revues de code, discuter des modifications et prendre des décisions collectivement.

La documentation facilite la refactorisation, la maintenance et l’optimisation des performances du code. Pendant le débogage, les développeurs peuvent s’appuyer sur la documentation du code comme point de référence pour trouver les erreurs de codage et en identifier la cause racine.

Une bonne documentation facilite un développement plus rapide, en évitant de perdre du temps à comprendre le fonctionnement du code et en recentrant les efforts sur l’application des mises à jour appropriées. Elle aide également à suivre les changements, afin que les équipes puissent rester en phase avec une base de code qui évolue fréquemment.

La documentation du code aide les nouveaux membres de l’équipe à comprendre le fonctionnement interne d’une base de code. Ils peuvent se familiariser plus rapidement avec la conception et la structure du code, et ainsi contribuer rapidement au projet.

Le code et la documentation vont de pair : ils doivent donc évoluer ensemble. Certaines bonnes pratiques applicables à l’écriture du code valent aussi pour la rédaction de la documentation. Voici quelques conseils utiles :

• Définir des standards de documentation du code

• Intégrer la documentation au codage

• Privilégier la clarté et la concision

• Documenter les décisions de codage

• Maintenir la documentation à jour

Comme les conventions de codage, les standards de documentation du code doivent être respectés. Ces standards comprennent une mise en forme cohérente, notamment l’indentation, les sauts de ligne et l’espacement pour la documentation de bas niveau. Pour la documentation d’API et les autres documentations de haut niveau et externes, les modèles et les outils de documentation du code peuvent aider à structurer le contenu et à harmoniser le style.

Cela peut consister à ajouter des docstrings une fois une fonction terminée, ou à insérer des commentaires intégrés lors de l’implémentation d’algorithmes ou d’une logique complexes. Rédiger la documentation en même temps que le code peut aider les développeurs à formuler leur raisonnement et leurs décisions, afin d’éviter que des détails essentiels ne se perdent en cours de route. Cette pratique peut demander un peu plus de temps au départ, mais elle peut devenir un réflexe naturel dans le processus de codage et accélérer le débogage, l’optimisation et la refactorisation à l’avenir.

Une documentation excessive peut nuire à la lisibilité du code. Les développeurs doivent privilégier un code propre et clair, puis ajouter la documentation nécessaire, de manière à ce qu’elle s’intègre naturellement au code.

En matière de concision, il est essentiel de trouver le bon équilibre. Par exemple, les fragments de code courts et simples peuvent ne nécessiter aucune documentation. À l’inverse, les algorithmes plus sophistiqués exigent une documentation qui explique leur logique sous-jacente de manière compréhensible pour des développeurs ayant différents niveaux d’expérience.

Cela inclut les choix de conception, d’architecture, de logique et d’algorithmes. Documenter ces décisions de codage, que ce soit dans un document interne de haut niveau ou dans une base de connaissances partagée, fournit du contexte pour les modifications futures.

Les équipes de développement doivent régulièrement revoir et mettre à jour leur documentation du code afin de s’assurer qu’elle reste exacte, complète et pertinente, et qu’elle reflète l’état actuel du logiciel. Intégrer la documentation au processus de revue de code peut faciliter ces mises à jour régulières.

La plupart des IDE disposent d’extensions ou de plugins pour générer de la documentation du code, mais d’autres frameworks et outils peuvent aussi contribuer à automatiser le processus. Voici quelques générateurs de documentation courants :

• Doxygen

• GitBook

• Javadoc

• JSDoc

• Sphinx

Doxygen prend en charge plusieurs langages de programmation, comme C, C++, Java, PHP et Python. Il permet le rendu Markdown et peut produire de la documentation aux formats HTML, PDF et XML. Doxygen peut être personnalisé à l’aide d’un fichier de configuration et offre la possibilité de générer des diagrammes représentant les hiérarchies visuelles et les relations entre les classes et les fonctions.

GitBook propose une interface utilisateur pour rédiger et publier la documentation sous forme de site web, ce qui peut rendre la création de documentation interne et externe plus efficace. La plateforme permet également la synchronisation avec des référentiels GitHub ou GitLab.

L’outil Javadoc analyse les commentaires de documentation dans le code source Java afin de générer une documentation d’API au format HTML. Il peut documenter les classes, les constructeurs, les champs, les interfaces et les méthodes.

Comme Javadoc, JSDoc génère de la documentation d’API pour les projets JavaScript. Sa communauté open source a développé des modèles et des outils pour personnaliser la documentation.

Sphinx est principalement conçu pour Python, mais s’étend également à d’autres langages de programmation. Il prend en charge Markdown ainsi que son propre langage de balisage, appelé reStructuredText. Sphinx peut créer de la documentation dans différents formats de sortie et propose des références croisées pour établir des liens avec d’autres éléments de code.

Les générateurs de documentation se limitent aux annotations qu’ils rencontrent dans le code source. L’IA générative va plus loin : elle analyse un extrait de code précis et ajoute des commentaires qui décrivent son objectif et son fonctionnement. De nombreux grands modèles de langage (LLM) pour le code disposent de fonctions natives de génération de documentation.

Par exemple, IBM Bob peut générer des lignes de commentaires pour une seule méthode ou pour toutes les méthodes d’une classe. Parmi les autres outils similaires figurent GitHub Copilot, JetBrains AI Assistant, Mintlify et Tabnine.

Comme pour tout système d’intelligence artificielle, les développeurs doivent toujours vérifier que les résultats des outils de documentation du code fondés sur l’IA sont complets et exacts.