Lorsqu’il s’agit de documenter des développements, il existe plusieurs méthodes. Soyons direct, l’approche qui consiste à réaliser un document n’a aucune pérennité. Dès les premières phases de refactoring ou d’amélioration, la documentation ne sera pas mise à jour.
L’approche qui consiste à utiliser un Wiki est déjà plus souple et permet à plusieurs développeurs de collaborer sur la construction documentaire. Cependant, idéalement, il convient de limiter les changements d’environnements qu’un développeur peut être amené à faire pour mener à bien sa mission. Il y a deux environnements dans lequel le développeur évolue depuis son IDE (Integrated Development Environment).
Il y a tout d’abord le répertoire qui contient l’ensemble de l’arborescence du produit et qui se traduit sur le serveur de versioning par une branche dans un repository. Le format le plus utilisé est le markdown qui permet de créer des fichiers documentaires un peu agrémentés de mises en pages, sachant que par convention, un serveur de versioning affiche automatiquement le fichier README.md du répertoire visité.
Le deuxième environnement est le code lui-même, dans lequel il est naturel pour le développeur, d’intégrer au moins des commentaires qui lui permettront de retrouver la logique utilisée lorsqu’il se replongera, plus tard, dans le code. Comme défini dans PEP 8 (Style Guide for Python Code), les commentaires peuvent être de type « Block Comments » ou « Inline Comments ».
Les commentaires qui contredisent le code sont pires que pas de commentaires. Gardez toujours les commentaires à jour en priorité lorsque le code change !
Les commentaires doivent être des phrases complètes. Le premier mot doit être en majuscule, sauf s’il s’agit d’un identifiant commençant par une lettre minuscule (ne modifiez jamais la casse des identifiants !).
Les blocs de commentaires consistent généralement en un ou plusieurs paragraphes construits à partir de phrases complètes, chaque phrase se terminant par un point.
Vous devez utiliser deux espaces après une période de fin de phrase dans les commentaires comportant plusieurs phrases, sauf après la dernière phrase.
Assurez-vous que vos commentaires sont clairs et facilement compréhensibles pour les autres lecteurs de la langue dans laquelle vous écrivez.
Codeurs Python de pays non anglophones : veuillez écrire vos commentaires en anglais, sauf si vous êtes sûr à 120% que le code ne sera jamais lu par des personnes qui ne parlent pas votre langue.
PEP 8
Les « Block Comments » s’appliquent généralement à une partie (ou à la totalité) du code qui les suit et sont indentés au même niveau que ce code. Chaque ligne d’un commentaire de bloc commence par un # et un seul espace (sauf s’il s’agit de texte en retrait à l’intérieur du commentaire). Les paragraphes à l’intérieur d’un commentaire de bloc sont séparés par une ligne contenant un seul #.
Les « Inline Comments » doivent être utilisés avec parcimonie. Un commentaire en ligne est un commentaire sur la même ligne qu’une déclaration. Les commentaires en ligne doivent être séparés par au moins deux espaces de la déclaration. Ils doivent commencer par un # et un seul espace.
Bien que les commentaires dans le code soient indispensables pour le développeur, ils ne sont généralement pas facilement accessibles pour des développeurs utilisateurs du code déjà réalisé. Ces utilisateurs peuvent se référer aux fichiers markdown présents dans les répertoires, mais ceux-ci ne décrivent généralement que les actions d’installations et de démarrage rapide, c’est à dire des informations qui ont peu de chances d’évoluer rapidement. Pour les informations pouvant évoluer au même rythme que le code, il est préférable d’utiliser une génération automatique de documentation à partir du code.
Pour ce faire, le point de départ est le « Documentation Strings » défini dans PEP 8. Les « docstrings » sont décrits dans le PEP 257 qui met en avant les bonnes conventions, et entre autre le fait que le symbole """ qui termine un « docstring » multiligne doit être sur une ligne indépendante. Pour un « docstring » à une ligne, le symbole de fermeture """ doit figurer sur la même ligne. Ce « Python Enhancement Proposals » avait été complété par le PEP 224 qui décrivait les « doctrings » pour les attributs, mais qui a été rejeté.
Pour les adeptes de solution d’affichage documentaire public comme Read the Docs, les outils de génération documentaire automatique comme Sphinx et MkDocs sont un bon choix. Le principe consiste à générer une documentation stockée sur un repository public et de l’importer dans un site permettant l’affichage de pages statiques.
Si Sphinx est un peu plus long à mettre en oeuvre, il est incontestablement le plus complet et dispose d’un écosystème très riche.
MkDocs permet de lancer un serveur de développement et de construire la documentation avec un fichier de configuration au format YAML et des fichiers au format markdown. La génération de documentation depuis le code source nécessite d’utiliser des outils complémentaires.
Dans le même esprit, j’ai une préférence pour pdoc3 qui s’installe très vite et permet de générer rapidement une documentation à partir du code, tout en enrichissant la documentation générée à l’aide de fichiers complémentaires pouvant être inclus dynamiquement au moment de la génération.
Le package pdoc3 utilise des templates au format mako pour générer la documentation.