documenter son code

Pour faciliter le partage et la réutilisation de son code, il est important de le documenter. Cette documentation peut être intrinsèque au code source : les lignes de commentaire dans le code peuvent aider les réutilisateurs à bien comprendre comment celui-ci fonctionne. C’est ce que nous avons essayé de faire pour cet exemple.

Mais il est aussi recommandé de fournir un apparat suffisant au code source qui donne de précieuses informations sur le contexte de sa création ; à quel besoin il a répondu, dans quel projet de recherche il a servi. Faire le lien avec les produits de recherche qui lui sont liés est important. Dans l’autre sens, les résultats d’une publication peuvent être reproduits si on dispose d’un accès au code source.

Ce sont des identifiants uniques pérennes qui rendent possible la connexion entre le code source, les données traitées (elles mêmes conservées dans leur propre entrepôt) et les publications présentes dans une archive ouverte (en l’occurrence HAL)

Le Plan de gestion de logiciel reçoit les principales informations utiles à des chercheurs et chercheuses qui souhaiteraient reproduire le code source. Pour ce tutoriel, nous avons rempli le plan de gestion de logiciel correspondant à notre script minimal (en partant de la version pour R) ; voilà ce que ça donne :