La documentation et la thématique du legacy : une grande histoire d’amour (faux).#
Tout le monde dans la tech a déjà été confronté au classique :
“Elle est où la documentation ? Ah. Y en a pas…”
Ce genre de phrase est tellement connu que c’en est devenu un running gag dans l’IT.
Elle nous évoque à tous au moins une anecdote de notre parcours, probablement douloureuse à l’époque, aujourd’hui amusante, par l’innocence du junior que nous étions.
À la simple énonciation de cette phrase, le problème semble évident : l’absence de documentation.
J’en suis pour ma part pas convaincu…
Si vous pensez que je délire, réfléchissez au point commun entre toutes les documentations. Elles vieillissent…
Ça partait pourtant si bien…#
Une documentation, pour être pertinente, se doit d’être maintenue à jour. Or, si l’effort de créer de la documentation peut survenir, celui de la maintenir est (très) souvent négligé.
Incroyable, pour la toute première fois, vous avez enfin accès à une documentation sur un projet. Une vraie !!!
Votre joie sera de courte durée…
Il s’avère que le code ne fait pas ce que la documentation indique. Qui croire du coup ? La doc ou le code ? Vous êtes maintenant parti pour une longue séance d’archéologie pour comprendre l’historique, suivie d’échanges questions réponses avec le métier pour essayer de démêler le vrai du faux…
Sur un projet récent, le problème est encore facilement corrigeable. Le développeur toujours présent dans l’équipe peut mettre à jour la documentation via sa mémoire à la demande.
Mais concernant un projet legacy ayant connu plusieurs vagues de développeurs depuis la dernière mise à jour de cette documentation ?
On pleure…
Une documentation est un mauvais support de vérité.#
Malheureusement comme vous l’aurez compris, une documentation n’est pas une source fiable d’information.
Sur le principe, ça semble être une bonne idée, en pratique, c’est bien plus nuancé…
Le vrai effort de documentation d’un projet, il doit s’effectuer dans le code, et plus spécifiquement dans ses tests.
Les tests décrivent et valident les règles métiers. C’est un contrat écrit. La règle n’est pas respectée ? Le test va casser et vous signaler qu’il va falloir soit modifier le contrat car la règle a changé, soit réparer le code pour maintenir le contrat existant.
La documentation classique ne vous dira jamais quand elle n’est plus à jour…
C’est d’ailleurs le même problème avec les commentaires dans le code. Si un commentaire se contente de décrire ce que le code fait, il finira lui aussi à son tour par vieillir et ne plus être à jour… Il faut au maximum limiter son usage uniquement au strict nécessaire pour exprimer ce que le code ne peut pas décrire.
Est-ce qu’on doit alors abandonner l’effort d’écriture d’une documentation classique ?#
Non. Bien sûr que non.
Il reste des choses que le code et les tests ne peuvent expliquer.
Par exemple :
- À quoi sert le projet, l’objectif
- La première prise en main
- Les choix d’architecture importants
- Les raisons d’un choix de prime abord contestable
- Etc.
Autrement dit, le contexte.
Dans une solution legacy, bien souvent le code et les tests (trop peu nombreux ou manquants) n’arrivent plus à jouer ce rôle. Et c’est ainsi qu’on se met à empiler de la documentation écrite en long et en large pour tout afin de compenser.
Pourtant, le principe reste toujours le même. Si la solution n’est pas explicite, c’est qu’il faut la modifier progressivement pour qu’elle le devienne.
À chaque changement dans le projet, on clarifie le code et on ajoute des tests qui décrivent le comportement métier attendu.
De cette manière, on fiabilise l’information en la rendant incontestable.
Au final, la meilleure documentation, c’est celle qu’on n’a pas besoin d’écrire.
Le code décrit ce que le système fait. Les tests formalisent et vérifient ce qui est attendu. La documentation explique pourquoi c’est fait ainsi.