Dernier article sur ma série concernant la mise en place de la qualité dans un projet web. Mais c'est aussi un point essentiel : la documentation.
Cet article est le dernier article d'une série d'articles visant à énumérer les différents éléments de qualité à mettre en place au démarrage d'un projet.
Devinette : Comment garantir que votre projet soit à jeter à la poubelle dans quelques années, à coup sûr ?
Plus simplement encore qu'en codant avec le cul ou en utilisant des technologies qui sont dépassées.
Bon évidemment, vu le sujet du jour, vous avez bien deviné que je veux parler de l'absence totale de documentation.
Un projet non documenté est voué à s'engraisser de dette technique, et finira par connaitre un funeste destin.
S'il y a quelque chose que j'ai appris de mes années de développement, c'est qu'on n'est pas là pour deviner les choses. Jamais. Rien n'est implicite, tout doit être claires.
En tant que développeur, je ne dois pas avoir besoin de lire des pages et des pages de code pour comprendre comment utiliser une classe ou un utilitaire.
À ce titre, la documentation est un élément crucial qui permet de faciliter la compréhension du produit.
La nécessité de produire de la documentation est incontournable à cause de deux paramètres clés : la taille de votre projet et le temps. Plus le projet grandit, plus il devient difficile de garder une vue d'ensemble sur toutes les parties du code. Plus le temps passe, plus il devient difficile de se souvenir des choix d'implémentation initiaux.
Vous pourrez penser que j'en fait trop, que j'accorde trop d'importance à la documentation. Après tout, un projet fondé sur un framework suit un certain nombre de règles standardisées, et il est aisé de comprendre un projet juste en allant regarder les bons fichiers.
C'est vrai qu'une application Django, par exemple, sera toujours constituée de modèles, de vues, et un développeur habitué à utiliser le framework n'aura aucun problème à s'approprier le code. Il est vrai qu'il serait contre-productif de documenter le fonctionnement des modèles. Un lien vers la documentation officielle suffit. Et pourtant, il y a beaucoup d'autres choses à documenter...
Imaginons deux situations différentes.
Cette première situation est très banale, elle touche un nombre important d'organisations.
Le produit a été développé par une seule personne, un développeur chevronné qui a une vision à 360 degrés des problématiques. Les choix techniques sont standards, et grâce à ce super produit, l'organisation a vite grandi.
Pourtant, 10 ans après, le code est un cauchemar. Il ne ressemble à rien, certaines lignes de codes sont incompréhensibles, certaines choses ont l'air de n'avoir jamais fonctionné correctement.
Qu'est-ce qu'il s'est passé ?
Eh bien, l'organisation ayant vite grandi, il a fallu recruter. Certains étaient des juniors, certains sont venus et sont partis, et le temps passant, les équipes sont de plus en plus autonomes. Faute de documentation, ils sont contraints de deviner les choses, de réinventer la roue, d'improviser les réglages de leurs modules, etc.
Petit à petit, des quiproquos se font, du code qui ne respecte pas l'esprit du projet fait son apparition et personne ne sait plus ce qu'il fallait faire à la base. C'est l'effet larsen : les nouveaux développeurs voient du code bancal à côté du "bon" code, mais n'ayant aucune documentation, ils ne savent pas quel pattern suivre. Les mauvaises pratiques prennent le dessus et le produit devient un cauchemar à maintenir.
C'est seulement à ce moment-là que l'organisation prend conscience du problème et tente de mettre en place des règles de codage plus strictes. Il est donc crucial de documenter chaque étape de développement pour assurer la pérennité du produit et de l'organisation.
Vous avez fait votre site internet, disons votre blog personnel, avec votre framework préféré. C'est super, c'est facile, et c'est rapide.
Mais vous n'avez pas besoin de coder tous les 4 matins dessus.
Le temps passe, et puis un jour, vous trouvez un bug. Vous avez envie de le corriger, mais rapidement, vous réalisez que ce n'est pas aussi facile que ça de revenir sur le projet. "Comment j'avais mis en place mes modèles déjà ?", "Pourquoi j'avais fait ça ? C'est bizarre...", "Bon OK, cette fois, ça fonctionne. Par contre, comment je déploie déjà ? C'est sur quel serveur ?"
Sur le fond, c'est votre projet, donc aucun souci. Mais vous allez passer plus de temps à essayer de vous souvenir de tous le contexte que de temps à modifier votre code.
C'est exactement l'histoire de ce site, d'ailleurs. La doc est à jour, depuis.
Pour produire une documentation de qualité, l'une des solutions les plus populaires est Sphinx. Ce générateur de documentation open source est largement utilisé dans la communauté Python, et même au-delà. Vous l'avez forcément déjà vu, puisqu'il est à la base des documentations fournies sur readthedocs.
Sphinx permet de produire une documentation claire et structurée à partir de fichiers texte écrits en reStructuredText ou en Markdown, pour les adeptes de cette syntaxe. L'outil offre de nombreuses fonctionnalités intéressantes, telles que la possibilité d'insérer des images, des liens, des notes de bas de page et des exemples de code. Il peut même faire de l'auto-documentation du code Python, en lisant les docstrings des modules et en les insérant dans les pages générées.
Sphinx est facile à installer grâce à la commande pip install sphinx, et la commande sphinx-quickstart permet de créer rapidement un projet de documentation. Ensuite, il suffit de rédiger des fichiers texte pour générer votre documentation
Comme on dit souvent :
Trop de doc tue la doc
Afin de ne pas documenter trop de choses inutiles, il faut placer le curseur au bon endroit.
L'idée de départ, c'est qu'on ne laisse jamais un dépôt sans les instructions d'utilisation élémentaires. Il faut un point d'entrée. Ce point d'entrée est le fichier README du projet. Il doit prendre le développeur par la main, et lui indiquer :
Pour la suite, je préfère orienter le lecteur vers la documentation complète.
À l'intérieur de celle-ci, et par ordre d'importance, j'inclus :
Je mets volontairement la documentation du code tout en bas de la liste. Idéalement, le code doit être le plus clair possible et doit faire ce qu'il dit. On dit qu'il s'auto-documente. Dans certains cas, des docstrings bien sentis aideront le développeur à comprendre comment utiliser une classe ou une méthode.
C'est typiquement sur ce sujet qu'il est possible de trop documenter. Ne faites pas ça par exemple, ça ne sert à rien :
def sort_list_by_name(unsorted_list: List[str]) -> List[str]:
"""Sort a list of strings by name
Args:
unsorted_list (List[str]): List to sort
Returns:
List[str]: Sorted list
"""
return sorted(list, key=lambda x: x.lower())Ça n'a aucun intérêt, aucune valeur ajoutée. À la limite, si c'est pertinent, expliquez la méthode de tri utilisé. Ou mettez des exemples.
def sort_list_by_name(unsorted_list: List[str]) -> List[str]:
"""
Usage:
>>> sort_list_by_name(['a', 'Z', 'b', 'Y'])
['a', 'b', 'Y', 'Z']
"""Pour terminer, évitez de faire votre documentation dans un dépôt externe. Vous documentez un projet. Je vous conseille donc de versionner cette documentation directement avec le projet. Rangez la documentation dans un répertoire docs à la racine du projet.
Voilà qui conclut ce petit dossier sur la qualité.
J'ai maintenant hâte de reprendre une activité normale et outrepasser toutes ces bonnes pratiques que j'ai énuméré tout au long de ces semaines ^^
2022 - tominardi.fr