Blog // Exirel.me

Documenter ses applications

Par Florian Strzelecki - 19:18 - 23.11.2009

Tags : Python, Documentation, Programmation, Bonne pratique, Technique, autodoc

Le pouvoir de la documentation est immense, et mésestimé par beaucoup trop de monde, parfois même par ceux à qui elle serait le plus utile, les développeurs.

Une documentation peut faire gagner du temps aux développeurs, mais c'est bien plus que ça. Le fait de documenter ses applications va au-delà du fait de gagner du temps, ou de gagner en compréhension : c'est un signe de qualité.

Pour ma part, je considère que documenter mes applications est un devoir, et un gage de qualité. Avec une bonne documentation, je montre que mon application a été pensée et imaginée dans le bon sens.

Une bonne documentation, évidement, car une mauvaise est peut-être pire que tout finalement.

La documentation de Django

Image : La documentation de Django

Le code source : documentation technique obligatoire

Jacob Kaplan-Moss (je parle souvent de lui) a publié récemment une série d'articles intéressants sur la documentation. Dans sa première partie il indique ceci :

Auto-generated documentation is almost worthless.

Sans doute. Je suis peut-être un peu plus modéré dans mes propos : la documentation auto-générée à partir du code source n'est pas suffisante, et elle ne répond qu'à des besoins très spécifiques.

En fait, la documentation auto-générée n'est pas nécessaire. Par contre, documenter le code source l'est.

Mon expérience personnelle est parsemée de projets dont le code source n'était pas documenté, ou alors, de manière insuffisante. Certains étaient pires que tout, avec une documentation qui n'était pas à jour. Une immense perte de temps et un gaspillage d'efforts qui auraient pu être évités.

A quoi ça sert alors ? Quels sont les besoins ?

Ces besoins, ce sont ceux du développeur qui doit modifier et réutiliser le code de quelqu'un d'autre, voir le sien, après un long laps de temps.

Ces besoins demandent une documentation pointue et précise, une documentation qui corresponde exactement à la portion de code impactée, et pas à autre chose (et surtout pas à une ancienne version du code).

Mais ces besoins ne sont pas ceux de la compréhension globale : on parle ici d'un code isolé dans sa partie, indépendant du reste de l'application.

Cette documentation là ne permet pas de comprendre l'application, mais seulement un petit rouage à la fois. Et, mine de rien, c'est quand même très pratique. Mais pas suffisant.

Les "documents écrits", la documentation que tout le monde oublie trop vite

C'est celle qui a été écrite à la main, en dehors du code source. C'est d'ailleurs le sujet principal de JKM dans sa série d'article.

La documentation écrite à la main, comme un livre, est devenue indispensable pour moi, et celle de Django est d'ailleurs une bénédiction.

Dans le monde professionnel, c'est la documentation qui manque le plus. On peut toujours documenter (en partie) le code source même si ce n'est pas son propre code. Difficile par contre, d'écrire une documentation de l'application sans une excellente connaissance de l'ensemble.

Que mettre dans ces documents ?

Des tutoriels, un guide d'utilisation pour développeur, des exemples, et une référence technique complète : c'est le minimum que l'on puisse faire.

Des tutoriels pour permettre à quelqu'un de prendre en main l'application rapidement.

Un guide d'utilisation, expliquant les intentions de l'auteur, expliquant avec une bonne grammaire, de manière explicite et simple, pourquoi l'application est ainsi faite. Il faut, en lisant un guide, que le lecteur puisse comprendre votre application, et s'approprier sa philosophie, son fonctionnement général, ses concepts importants.

Des exemples pour expliquer concrètement les cas d'utilisations. C'est une façon de ramener le lecteur vers le concret, après lui avoir exposé les concepts de votre application.

Les références de l'application sont, cette fois-ci, comme un index détaillé de votre application. Maintenant que le lecteur sait dans quel sens va votre application, et comment s'orienter dans ses différentes parties, il a besoin d'en connaître les détails plus concrets, plus techniques, plus fins.

C'est là, avec les références que l'on serait tenté de fournir la documentation auto-générée. Je dirais que c'est mieux que rien, mais que ce n'est vraiment pas la même chose.

La clé de la compréhension

Un développeur, pour bien faire son travail, doit comprendre ce qu'il fait pour travailler.

Cela fera peut-être sourire vaguement certains devant cette évidence, mais j'ai pu constater à plusieurs occasions que ce n'était pas si évident que ça pour tout le monde.

Le "tu ajoutes ça ici et ça fait ça" n'est pas une explication suffisante à la compréhension. C'est une description fonctionnelle, mais il n'y a pas de compréhension là dedans. Et sans cette compréhension, le développeur emprunte doucement mais sûrement la voie de la magie noire applicative (quand tout est magique dans l'application, parce que vous ne savez pas pourquoi ça marche comme ça).

"Tant que ça marche pourquoi s'embêter ?" est un signe de fainéantise qui peut devenir fatal au futur de l'application.

La documentation en tant que documents externes au code source permet une compréhension globale de l'application, elle offre la clé d'accès vers la démystification des fonctionnements de l'application. Vers la maîtrise des arcanes du développement.

Elle donne le pouvoir au développeur de faire quelque chose de bien. A lui de l'utiliser, évidemment.

Inspiration et conclusion

Cela fait quelques temps (mois, années plutôt ?) que je réfléchis sur la documentation. Mes réflexions m'amènent à penser qu'il n'y a pas de recette miracle : il faut l'écrire, trouver un style et s'y tenir, la rendre disponible et surtout compréhensible par les autres.

Jacob Kaplan-Moss, dont je me suis abondamment et librement inspiré pour cet article, propose une série de bonnes pratiques pour écrire la documentation, n'hésitez pas à consulter ses écrits.

J'ai lu récement un article sur le Framablog : Montre-moi tes commentaires et je te dirai si tu es un bon développeur. Je vous en conseille la lecture.

Brrr... des fois, j'ai peur, rien qu'à imaginer tous ces codes sources mal écrits et mal documentés. Car je sais qu'un jour, il y aura quelqu'un, peut-être moi, qui sera obligé de s'en occuper.