Documentation de code

Ce document a été produit à partir de matériel pédagogique et de nombreuses discussions concernant le module TER (Travaux d'Etudes et de Recherche) de la Maîtrise Informatique de l'Université Bordeaux 1.

Lorsque vous produisez du code, il est souhaitable d'accompagner ce code d'une documentation. Celle-ci peut se décomposer en plusieurs parties relativement indépendantes.

Le code

Le principal document qui renseigne sur un code est le code lui-même. C'est le seul à être complet. Il est donc important qu'il soit lisible, en s'aidant au besoin de commentaires.

Manuel utilisateur

Il est généralement nécessaire de fournir un documentation à l'utilisateur (application) ou au client (bibliothèque/paquetage).
Cette documentation se compose au minimum Les droits d'utilisation, manuel d'installation et prise en main peuvent parfois être regroupés dans un fichier README, placé au sommet de la distribution du logiciel.
La documentation détaillée peut être "en ligne" sous la forme de dialogues, de pages html ...
On n'oubliera pas dans le manuel d'installation de bien préciser les outils nécessaires au bon fonctionnement du logiciel, sans oublier de préciser les versions avec lesquelles le logiciel a été testé.

Manuel de maintenance

Ce manuel est destiné à permettre l'évolution du code, par une ou plusieurs personnes souvent différentes de l'auteur du code original.
Le premier objectif du manuel de maintenance est de présenter de façon concise l'architecture du code, de façon à permettre au lecteur de consulter uniquement les parties qui le concernent, et également de pouvoir juger des effets potentiels des modifications qu'il souhaite apporter. Cette architecture peut être décrite par un ou plusieurs schémas, en utilisant des notations claires ou encore standardisées comme les diagrammes de classes UML (Unified Modeling Language)
Le second est d'éclaircir des morceaux de code pour lesquels des explications sous forme de commentaires sont peu adaptées. Par exemple, pour décrire une structure de données ou un algorithme complexe, l'arborescence d'une interface graphique ...
On trouvera également dans ce document les éléments permettant une réutilisation de certaines parties du code indépendamment du reste du logiciel.
Le manuel de maintenance doit décrire également les jeux de tests qui ont servi à la validation du logiciel, et les résultats obtenus.
On trouvera généralement dans le manuel de maintenance des propositions pour l'amélioration du logiciel, et en particulier s'il y a lieu, la liste des erreurs constatées.
Si le développement de l'application a utilisé certains outils particuliers (par exemple une bibliothèque), cela doit être précisé dans le manuel de maintenance, de façon à ce que les mises à jour de ces outils puissent le cas échéant être intégrés dans le cadre de la maintenance.
Le manuel de maintenance n'est surtout pas là pour paraphraser le code, ni pour essayer de (mal) remplacer des outils.
Par exemple, dans la documentation d'un programme écrit en Java, une liste des classes et de leurs méthodes n'a pas lieu d'être, cette liste étant obsolète dès que l'on va modifier le code existant. Les outils javadoc du JDK ou encore etags d'emacs ont une efficacité bien supérieure !
Dans le cas de la description d'algorithmes ou de structures de données, il est important de vérifier qu'une telle description n'existe pas déja (en mieux) dans un ouvrage avant de vouloir à tout prix fournir sa propre explication. Une référence précise, comportant le titre de l'ouvrage, le nom de l'auteur, l'année de publication, l'éditeur et les numéros des pages concernées est alors préférable. Il convient aussi dans ce cas de faire correspondre les noms de variables utilisées dans le code à ceux utilisés dans la description de l'algorithme.

Rapport de projet

Dans le cas d'un projet dans le cadre d'un enseignement, il est  nécessaire d'accompagner le résultat du projet (le code et ses manuels) d'un document expliquant Ce rapport n'est pas destiné à accompagner le projet, mais à faciliter son évaluation.
Il est fréquent de trouver dans ce rapport une présentation du domaine d'application du projet. Les connaissances de l'évaluateur du projet peuvent en effet être différentes de celles des utilisateurs. Si cette présentation doit également être communiquée aux utilisateurs, il est préférable d'en faire un document indépendant.

Le cahier des charges

Il est souvent nécessaire de rédiger dans le cours d'un projet un, voire plusieurs cahiers des charges. Ce document permet C'est une sorte de contrat à la fois vis à vis du client, mais aussi entre les membres de l'équipe de développement.
Le cahier des charges doit contenir Une version élaborée du cahier des charges peut également contenir les jeux de tests à utiliser pour la validation du logiciel, une première version de son architecture, voire parfois une spécification précise des fonctions à implémenter. Dans le cas d'un projet en Java, cette dernière prendra la forme d'un ensemble d'interfaces.

Qualités d'un document

Les qualités d'un document sont son exactitude et sa lisibilité.
L'exactitude d'un document se traduit par Sa lisibilité est liée à sa forme : Il est important de ne pas attendre le dernier moment pour rédiger la documentation. Une relecture attentive est souvent nécessaire pour arriver à un résultat correct (y compris pour le code !). Quel que soit le travail fourni, seul le résultat compte et ce résultat est l'ensemble des documents produits.