@casanowe
Jeudi après-midi vous êtes en train de coder frénétiquement, le casque isophonique sur les oreilles, en mode « faut pas me déranger sauf si c’est la fin du monde« .
Christophe et Pierre débarquent devant vous dans l’open-space. Malgré votre effort pour leur montrer que vous êtes concentré, ils tiennent absolument à vous parler et se dirigent vers votre bureau. Vous tentez de rester super concentré, en vous disant que si vous ne bougez pas, ils ne vous verront pas. Mais bon, comme vous êtes une personne sympa, à l’écoute, vous retirez votre casque, et là, la question de Pierre tombe :
« Nicolas, sur ton module Vanessatra, elle est où ta doc ? »
Il se trouve que vous avez créé il y a plusieurs mois l’un des composants de chargement de fichiers du système. A l’époque c’était quelques lignes, qui sont devenues un vrai projet, avec des vrais clients qui s’en servent. Vous avez écrit un README en markdown, attaché au projet, et pour vous c’est ça la doc.
Pierre est le tuteur de Christophe, qui a rejoint l’équipe, et qui doit ajouter une fonctionnalité sur ce produit.
A priori votre documentation est incomplète et en plus, elle n’est pas à jour. Entre temps vous êtes passé sur PostgreSQL, et une partie du README est obsolète.
Bref, psychodrame, que faut-il faire et comment gérer finalement la documentation d’un projet ?
Je vous propose quelques pistes et idées.
Comment documentez-vous vos projets ?
Javadoc, Word, schémas, diagrammes, Markdown, AsciiDoc… nous avons tous écrit de la documentation sur nos projets.
J’ai écrit des lignes et des lignes de documentation, de spécifications et dessiné un sacré nombre de schémas. Lorsqu’il s’agit de faire des schémas ou des diagrammes, Microsoft Visio est pratique. J’utilise aussi LucidChart un équivalent en ligne. Sur Mac je n’ai pas trouvé pour l’instant de logiciel pratique.
J’utilise Markdown ou AsciiDoc lorsque je dois expliquer une procédure d’installation ou les pré-requis, et que je souhaite que la documentation soit stockée avec le code source, et qu’elle soit versionnée en même temps que les évolutions de celui-ci.
Il existe des outils plus évolués comme Structurizr par exemple, qui permet d’envoyer une description d’un projet sous forme de code Java, et qui génère en retour un diagramme simplifié. C’est un peu l’équivalent du tableau blanc où vous avez l’habitude de dessiner, sauf qu’ici l’outil est intégrable à un build continu par exemple. Simon Brown, son créateur, sera à Devoxx France 2016, il est invité.
Il est toujours plus intéressant d’expliquer les Pourquoi d’un projet, plutôt que de se focaliser que sur les Comment ou les Quoi. En débutant sa documentation par un paragraphe de justification ou d’historique, vous donnerez un contexte à votre code. Ensuite seulement, vient la description de l’architecture et la documentation plus technique sur le projet.
A titre personnel, je ne rédige plus vraiment de spécifications techniques ou fonctionnelles, et je vais vous expliquer pourtant comment nous arrivons à travailler en équipe, sans problèmes de communications.
Pour quel lecteur ? Qui vous lira (ou pas) ?
Pour qui suis-je en train d’écrire ce document ? Que doit-il connaître avant de commencer à lire ma documentation ? Quels problèmes doit-elle résoudre ?
Nouveau développeur, client, contributeur sur votre projet open-source, responsable technique, chef de projet, utilisateur final…
Les limitations de la documentation classique
Ecrire de la documentation, puis s’assurer qu’elle est à jour, peut représenter une charge de travail trop couteuse pour certains projets. Si finalement votre module ne sera utilisé que par 2 personnes internes, quel est l’intérêt économique d’écrire un roman de 50 pages sur l’installation ?
L’effort de documenter un projet ou une procédure d’installation doit être limité dans le temps, selon la cible visée. Il est évident qu’un guide du contributeur pour Docker doit être très complet et détaillé, vu le nombre de personnes qui souhaitent contribuer à ce projet. A contrario, votre petite librairie sympa en Go, à usage interne, n’a pas forcément besoin d’une documentation parfaite.
Oui mais alors comment éviter d’être dérangé (blague) et comment documenter ?
Le code c’est de la doc
Evidence toujours bonne à redire : le code d’un logiciel est fait d’abord pour être lu par un humain, ensuite par une machine. Et une machine, je pense à la VM Java par exemple, est à même d’optimiser largement l’exécution du code, ce qui rend bien souvent inutile l’optimisation à tout prix d’un bout de code. Pensez d’abord que vous même, et peut-être un autre développeur, relira ce code dans 10 jours ou dans 3 mois.
En êtes-vous fier ? Pouvez-vous expliquer à votre fils de 10 ans ce que fait cette fonction ? Avez-vous effacé la balise @author tellement vous regrettez ce qui vient d’être écrit ? Avez-vous essayé de relire le code après une soirée trop arrosée pour voir si vous le comprenez toujours ?
Bref chacun sa technique, mais du code propre est la base d’une documentation vivante et à jour. Cela s’effectue avec des techniques de modélisations (DDD mais pas que).
A contrario, trop de javadoc/scaladoc pour moi, c’est aussi un pattern que le code est trop compliqué. Ne trollez pas sur Scala les chéris, les plus belles oeuvres que j’ai vu sont dans le monde Java. Mais bon, lorsque tu as 50 lignes de Javadoc pour 10 lignes de code, hem, ça poutre pas des masses.
Les tests aussi
Tester c’est documenter. Cela permet à un nouvel arrivant de comprendre ce que vous avez voulu faire, quels sont les cas limites de votre code, et bon sang, oui vous avez vraiment écrit ce code après le pot de départ d’un collègue. Mais passons.
Les tests unitaires, d’intégration, de désintégration, de comportements, en production, bref les « Tests » en général représentent un excellent moyen d’expliquer comment fonctionne votre projet.
Et enfin l’humain, la meilleure documentation
Enfin pour terminer, avec mes années d’expérience, j’ai trouvé que l’humain est plutôt pas mal aussi pour documenter et venir expliquer comment fonctionne un logiciel. Ce que l’on peut dire c’est que rien ne remplace une tasse de café échangée, autour d’un écran, où d’un air désolé vous expliquerez à Christophe pourquoi vous avez écrit ce code à 22h30 après le pot de départ de Bob, et que oui, c’est de la merde.
L’humain évidemment peut démissionner ou partir élever des e-chèvres sur Farmville, donc un peu de documentations « old-school » c’est pas mal aussi.
Mais c’est le meilleur outil jamais inventé, pour expliquer le fonctionnement d’un logiciel, pour aider Christophe, le petit nouveau, et surtout pour créer un lien social entre vous.
Dans le code écrit récemment d’un projet, sur une partie un peu hard-core j’ai laissé ce commentaire pour que le prochain relecteur vienne me voir. Ce sera l’occasion de prendre un café, que je me force à améliorer ce code et à le rendre plus lisible.
// TODO venir voir Nicolas le jour où quelqu'un lit ce code // Ici un mot d'excuse pret à découper // --------------------------------------------------------- // | J'ai écrit du code à l'arrache et je suis désolé | // ---------------------------------------------------------
Et donc toute ressemblance avec la réalité, tout ça, bla bla bla
Documentez et codez
Pour aller plus loin, je vous recommande le livre « Living Documentation » par Cyrille Martraire.
Bonjour,
Pour avoir un code parlant, qui porte sa propre documentation tu parles de techniques de modélisation comme DDD.
J’aurais mis en avant le Clean code pour avoir un code qui utilise le même vocabulaire que les analystes.
Et merci pour l’article, il est simple et clair.
Cordialement, Nicolas
Pour les schémas sur Mac, je conseille vivement Omnigraffle 🙂