Catégories : CodeTechnologie

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.

Partager sur les réseaux sociaux

Koffi Sani

African Optimist Citizen | IT Engineer | Budding Entrepreneur | On the lookout of ideas that will change Africa | I sometimes talk about code at https://code.koffisani.dev

Partager
Ecrit par
Koffi Sani

Articles récents

De la nécessité de poser les bonnes bases de vos projets logiciels

L'une des préoccupations fondamentales de l'Ingénieur c'est de s'assurer de la qualité du produit que…

7 mois

Dieu est juste, pour le Paris Saint-Germain aussi

Bien que Paris Saint-Germain ne soit pas favori face au Bayern Munich, il ne serait…

1 an

Education au numérique : ce que je propose

Ce samedi, ce fut une fois encore l'occasion pour moi de passer sur le plateau…

1 an

Voici le nouveau Github Student Pack, mais il faut ceci pour certains étudiants

Vous avez déjà entendu parler de "Github Student Pack" ? C'est une offre gratuite de…

2 ans

LinkedIn pour certifier vos compétences ?

Ce réseau social qui se veut différent des autres de part son caractère professionnel est…

3 ans

Comment donc choisir son framework ?

Le développement d’applications informatiques implique souvent sa normalisation et son accélération. Les développeurs sont souvent…

3 ans