Conception des chaînes éditoriales

Chaque langage de programmation propose un moyen d'insérer des commentaires au sein du code. Il s'agit de caractères spéciaux reconnus par le programme qui traite le code (compilateur ou interpréteur) et qui agissent comme des bornes d'exclusion. L'ensemble des caractères contenu entre la chaîne de caractères de départ et la chaînes de caractères de fin sont ignorés à la compilation ou l'interprétation.

Par exemple, au sein des langages C ou C++, deux méthodes coexistent pour assurer l'insertion de commentaires :

• la chaîne « // » pour débuter le commentaire et le retour chariot pour le terminer ;

• la chaîne « /* » pour débuter le commentaire et la chaîne « */ » pour le terminer.

Pour l'exemple, on pourra consulter un fichier de sources en accès libre tel que ceux du système d'exploitation Linux disponible sur la plateforme github comme le fichier cpu_rmap.c. On constate ainsi que le fichier contient des informations en en-tête (licence, objet du fichier de sources) et que chaque fonction contient son propre commentaire.

Le premier usage des commentaires au sein du code source consiste à documenter le fonctionnement d'un fragment de code pour permettre à d'autres développeurs de bien comprendre son usage et faciliter ainsi sa maintenance et ses évolutions.

Certains environnements de développement proposent d'exploiter la logique des commentaires pour assurer d'autres fonctions d'assistance aux développeurs dans la maintenance de leur code source. Par exemple, le logiciel Eclipse propose un système de tâches s'appuyant sur les commentaires. En ajoutant les commentaires « TODO », « FIXME » ou « XXX », un développeur ajoute une tâche dont la description est définie à la suite du mot-clé.

Un autre usage courant des commentaires est leur exploitation pour la production de documentations externes au code. La plupart des langages intègrent ainsi une logique de commentaires particulière ; des logiciels externes d'analyse de code source prennent le relais lorsque ce n'est pas le cas (comme Doxygen pour les langages C et C++). Des chaînes de caractères spécifiques sont insérées dans les commentaires et utilisées par l'algorithme de génération de la documentation pour déterminer quels commentaires correspondent à quels fragments de la documentation. La sortie du processus génère un site HTML ou un document PDF reprenant la description de l'ensemble des fonctions.

Ying, Wrigth & Abrams (2005^[1]) ont mené une étude sur l'usage des commentaires, et plus particulièrement du système de tâches d'Eclipse, au sein d'un dépôt de code source interne à la société IBM. Ils ont ainsi établi toute une typologie d'usage (communication entre équipes, indicateur de portion à changer dans une tâche plus importante, mémorisation de tâches passées, tâches en cours, tâches futures) et répertorié manuellement les différents commentaires au sein de ces catégories. Ying et al constatent ainsi que le système de commentaires en général, et celui de tâches en particulier offre un cadre permettant à la fois de communiquer entre équipes de développement et plus généralement, facilite la maintenance du code source en permettant l'inscription d'indications de maintenance au sein même du code.