Documenter son code

Bonjour, une question qui n'est pas très technique aujourd'hui mais j'entends souvent parler de " Bien documenter son code c'est indispensable en entreprise ". Donc j'aimerais savoir, c'est quoi exactement "Faire une doc " ?

Merci d'avance

Salut Yanis,

Beaucoup de choses à dire à ce sujet. Ça peut aller de juste rajouter des docstring dans tes fonctions, à rajouter des annotations de type partout et faire des tests unitaires.

Une bonne façon de savoir si ton code est suffisamment documenté, est de revenir sur des anciens projets que tu as fait. Si tu es capable très rapidement de voir comment utiliser ton script, ce que fait chaque fonction, ce que chaque fonction va retourner et comment elles fonctionnent les unes avec les autres, à quoi servent les modules etc, c'est que ton code doit être assez bien documenté.

Il faut faire attention de ne pas tomber dans l'écueil inverse, à savoir trop documenter. Si tu rajoutes un commentaire à chaque ligne de code, ça n'est pas utile, ton code doit être suffisamment explicite avec des noms de variables, de fonction et un découpage de base suffisant pour comprendre comment il fonctionne sans avoir besoin de décrire presque chaque ligne de code.

Donc c'est une bonne balance à trouver, mais l'idée surtout en entreprise c'est que n'importe qui puisse arriver dans une "codebase" et comprendre comment les choses fonctionnent.

Pour des grosses bases de code tu peux carrément faire des documentations comme on retrouve dans la plupart des librairies / packages (Django, FastAPI, etc).

Super merci, quand j'entend les gens en parler, ça me paraissait être quelque chose de plus complexe que ça mais finalement, il n'y a rien de sorcier ( en tout cas de mon point de vue ).