La documentation est aussi importante que votre code

Beaucoup de développeurs n’ont de préoccupation que l’écriture d’un code qui marche et qui fait donc le travail. Toutefois, un logiciel n’est jamais terminé. Il est appelé à évoluer, surtout lorsqu’il s’agit d’un travail en équipe. Et dans la majeure partie des cas, ceux qui le font évoluer ne sont pas à l’origine du projet. Et pour ce faire, ils ont besoin de savoir ce que fait le code, comment il le fait, éventuellement pourquoi, comment contribuer, … C’est là où rentre en jeu la documentation.

J’ai déjà gouté plusieurs fois à la peine du code d’autrui, du code que quelqu’un d’autre a écrit. Ce n’est pas du tout facile. Je vous l’avoue, c’est horrible. Et les développeurs sont unanimes là-dessus, il n’y a pas plus pénible que de travailler sur un projet non (ou mal) documenté, d’après les résultats du sondage de GitHub, le réseau social des développeurs.

Que ce soit pour un projet Open Source, ou un projet propriétaire, le souci est le même. On m’avait soumis, il y a de cela un mois, un projet à améliorer, une amélioration qui m’a suffisamment pris du temps pour me retrouver. Non seulement les variables ne sont pas nommées intuitivement, mais aussi aucune ressource ne permet de s’enquérir sur le fonctionnement de l’application. Voici donc quelques raisons pour lesquelles vous devez (bien) documenter votre code.

Après 6 mois, vous ne reconnaitrez plus votre code

La plus grande tentation c’est quand vous dites : « Je suis seul sur le projet, je sais ce que je fais. » Ou « Je n’ai pas de temps pour écrire une documentation. » En tant que développeur, vous vous promènerez de projets en projets, et serez dans l’incapacité de garder indéfiniment par cœur l’idée et la philosophie de tous vos projets. Plus le temps passe, moins vous vous souvenez de ce que fait une fonction, une classe, ou encore une variable. Vous avez besoin d’une documentation pour vous retrouver. C’est donc pour votre propre intérêt qu’il est important de documenter votre projet.

La documentation fait exister le projet

S’il n’est pas documenté, le projet n’existe pas. Non seulement il doit être documenté, mais il doit être expliqué, enseigné et démontré. Faites cela, et les gens seront excités –non pas pour la documentation—mais pour le produit. — Mike Pope

La plus grande frustration des développeurs c’est lorsqu’ils s’intéressent à un produit et par la suite, ils ne trouvent aucune ressource pour démarrer ou avancer. En ce moment où la technologie s’innove tous les jours, les gens n’apprennent que sur internet, à travers les documentations et tutoriels. Lorsque votre projet n’a rien de ce genre, personne ne pourra s’en servir, ni l’utilisateur final, ni le développeur.

Documenter c’est inviter à collaborer

Vous ne pourrez pas y arriver seul.

C’est bien vrai dans le monde informatique, plus spécifiquement pour les développeurs. Et documenter ressemble à une invite à l’endroit de la communauté, tant dans une entreprise que dans la communauté open source.

Une documentation qui explique clairement le process du projet, tel que le guide de contribution et le code de conduite, est très appréciée par des groupes sous représentés à l’exemple des femmes. — Open Source Survey 2017

Toutefois, il n’y a pas plus difficile pour le développeur que l’écriture d’une documentation. C’est pourquoi dans des structures de tailles conséquentes, il y a des équipes en charge de la documentation. Et pour ceux qui ne sont pas dans ces entreprises, ce n’est pas une excuse pour négliger la documentation.  Dans un prochain article sur http://code.koffisani.ga, nous aborderons comment écrire une bonne documentation. D’ici là, si vous avez une suggestion ou critique, prenez la peine de commenter ci-dessous.

Also published on Medium.