Documentation du Code: Le Guide complet du Débutant

Vous êtes un peu dans votre premier travail de programmation, et les choses deviennent plus faciles. Au début, tout le code auquel vous avez dû faire face pourrait vous avoir submergé et confus, mais vous commencez à vous en rendre compte. C’est génial ! Maintenant, vous vous demandez comment faire passer le code que vous écrivez au niveau suivant. Bien qu’il y ait beaucoup de choses à apprendre sur votre pile de programmation, dont beaucoup feront de vous un meilleur programmeur, il y en a quelques-unes qui vous serviront, quelle que soit la pile dans laquelle vous travaillez. L’un d’eux est la documentation de code.

De nombreux développeurs n’écrivent pas assez de documentation, soit parce qu’ils ne voient pas la valeur, soit parce qu’ils ont l’impression de ne pas avoir le temps. Vous n’avez pas besoin d’être l’un de ces développeurs. Avec un peu de temps et beaucoup de pratique, vous pouvez ajouter de la documentation pour votre code, ce qui en fait une joie à utiliser pour vous et pour tous ceux qui le suivent.

Une bonne documentation se présente sous de nombreuses formes

Lorsque la plupart des développeurs pensent à la documentation de code, ils pensent aux commentaires. Les commentaires peuvent être des ajouts précieux au code, mais ils ne sont pas la seule définition de la documentation. La documentation est tout ce que vous écrivez en plus de votre code pour aider quelqu’un d’autre à comprendre comment cela fonctionne. Vous n’y pensez peut-être pas de cette façon, mais un bon exemple de documentation de code est un fichier README. Un bon exemple de documentation de base est l’Express.fichier js README. Il répond à plusieurs questions importantes sur le framework et vous explique comment l’inclure dans votre projet, comment l’installer et comment exécuter des tests.

Une bonne documentation peut également se présenter sous la forme d’une documentation API. Encore une fois, Exprimez.js fournit un excellent exemple. Cette version de la documentation est davantage une bibliothèque de référence pour les développeurs utilisant le framework. Vous trouverez des réponses aux questions sur ce que font les fonctions individuelles et ce que signifient les différents paramètres de ces fonctions. Sans cette documentation de qualité, Express n’aurait pas autant d’équipes qui l’utilisent qu’elles.

Et bien sûr, vous pouvez également utiliser des commentaires en ligne pour documenter le code. Ce genre de commentaires ne sont généralement pas utilisés pour enseigner le code à des personnes en dehors de votre propre équipe. Au lieu de cela, ils sont utiles pour expliquer ce qui se passe dans un morceau de code particulier à vos coéquipiers ou à votre futur moi.

Pourquoi Vous devriez Documenter Votre Code

Comme indiqué ci-dessus, de nombreux développeurs ne comprennent pas le but de la documentation du code. Ils diront que le bon code devrait s’auto-documenter et que vous ne devriez pas avoir besoin de l’expliquer. Ces gens ont, en un mot, tort. La vérité est qu’une bonne documentation est une partie essentielle de toute base de code. Pourquoi? Parce que les gens ne devraient pas avoir besoin de lire tout votre code pour comprendre ce qu’il fait. “Personnes” dans cette phrase précédente peut désigner n’importe qui, y compris votre futur moi.

La vérité est que souvent, les “personnes” qui auront besoin de comprendre le code après son écriture, c’est vous. Ce petit bout de logique qui semblait si intelligent lorsque vous l’avez écrit il y a six mois pourrait être difficile à comprendre aujourd’hui. Si votre code est bien documenté, vous n’avez pas besoin de passer du temps à essayer de comprendre ce qu’il fait. Vous pourrez passer quelques secondes à regarder la description, puis revenir à ce sur quoi vous travaillez en ce moment.

Si vous avez la chance de travailler sur du code utilisé par des dizaines ou des centaines de développeurs, une bonne documentation est encore plus importante. La vie de vos utilisateurs sera considérablement améliorée par votre temps passé à rédiger une bonne documentation, et ils vous en remercieront. Littéralement!

La clé à retenir est qu’une bonne documentation permet d’économiser plus de temps qu’il n’en faut pour l’écrire. C’est peut-être votre heure, ou celle des membres de l’équipe, ou même des personnes que vous ne rencontrerez jamais. Parfois, la rédaction de documentation vous aidera même à reconnaître une partie de votre code trop compliquée pour que vous puissiez la simplifier.

Quelques erreurs de documentation courantes

En tant que développeur junior, vous allez devoir passer du temps à apprendre ce qui rend la documentation efficace. La bonne nouvelle est que vous pouvez apprendre des gens qui vous ont précédés afin d’éviter les erreurs courantes.

Sous-documentation

Une erreur courante que je vois avec la documentation de code est de documenter des informations déjà clairement visibles. Par exemple, les développeurs paresseux ajouteront de la “documentation” à une fonction en ajoutant un bloc qui fournit le nom d’une fonction ainsi que les noms de chaque paramètre et leurs types individuels. Ce type de documentation est inutile ! Il faut quelques secondes à quelqu’un pour lire le nom de la fonction et les paramètres qu’elle prend. Ce n’est pas de la documentation, c’est juste de la répétition. Au lieu de cela, la documentation devrait inclure un peu d’informations sur ce que fait la fonction et comment chaque paramètre modifie le comportement de la fonction ou pourquoi elle est nécessaire.

Sur-documentation

Le schéma inverse peut également poser un problème sérieux. Pour éviter d’écrire trop peu de documentation, certains développeurs aiment écrire l’explication de chaque minuscule bout de logique contenu dans une fonction. Ils documentent méticuleusement toutes les raisons qui ont présidé à la création de la fonction. Au moment où ils ont terminé, ils ont peut-être passé autant de temps à écrire la fonction qu’à écrire la documentation. Pire encore, la documentation est souvent difficile à comprendre et prend autant de temps que la lecture du code. Ce genre de documentation est aussi une perte de temps. Au lieu de cela, une bonne documentation donne une explication de base du quoi et du pourquoi. S’il y a des parties du code particulièrement délicates à comprendre, alors la documentation devrait expliquer uniquement ces parties.

S’appuyant sur des tests pour documenter

De temps en temps, vous rencontrerez quelqu’un qui prétend que la meilleure forme de documentation est les tests unitaires. Cette approche présente une lacune majeure: la lecture des tests unitaires est souvent aussi difficile à faire que la lecture du code lui-même. Tout développeur souhaitant apprendre ce que fait votre code aura un premier pas important pendant qu’il traquera et lira tous vos tests unitaires. Beaucoup abandonneront juste avant de réaliser ce qu’ils ont entrepris de faire. Bien que les tests unitaires soient un ajout précieux à toute base de code, ils ne remplacent pas une bonne documentation.

Façons de faire passer la documentation au niveau supérieur

Si vous travaillez sur une grande base de code, la documentation du code peut sembler intimidante, surtout si vous n’avez pas fait preuve de diligence pour documenter le code jusqu’à présent. On pourrait avoir l’impression que vous essayez de faire bouillir l’océan. Si vous avez une grande base de code, ou si vous savez qu’une bonne documentation est essentielle, vous voudrez peut-être étudier des outils de documentation de code automatisés. Ces outils simplifient considérablement le processus de rédaction d’une documentation cohérente et de qualité pour toute une équipe. Un outil comme GhostDoc examinera intelligemment votre code et utilisera les modèles établis par votre équipe pour lancer votre documentation en appuyant sur quelques touches. Les outils de documentation automatisés suppriment l’une des autres raisons courantes de s’opposer à la rédaction de la documentation: cela prend trop de temps.

Une fois que vous disposez d’une documentation cohérente, d’autres outils vous permettent de partager cette documentation facilement. Les outils de documentation automatisés facilitent le développement d’une bonne documentation pour des éléments tels que les API publiques fournies par votre code.

Commencez dès aujourd’hui

Écrire une excellente documentation est beaucoup plus facile que d’écrire du code. Contrairement au code, la documentation n’est pas une entreprise tout ou rien. Commencez avec un objectif d’écrire une bonne documentation pour une fonction chaque jour. Ce genre de pratique crée des habitudes saines, et vous verrez le gain sur la route lorsque vous passerez beaucoup moins de temps à essayer de comprendre des parties de votre base de code. Au fil du temps, cela commencera à se sentir mal lorsque vous écrirez du code qui n’a pas une bonne documentation. Vous commencerez à indiquer à vos collègues des moyens d’améliorer la documentation lors de la révision du code. Une petite habitude améliorera le code de votre équipe pour l’ensemble de votre entreprise.

Découvrez comment GhostDoc peut vous aider à simplifier vos commentaires XML, à produire et à maintenir une documentation d’aide de qualité.

À propos de l’auteur

Eric Boersma

Auteur contributeur

Eric Boersma est un développeur de logiciels et un responsable du développement qui a tout fait, de la sécurité informatique dans les produits pharmaceutiques à la rédaction de logiciels de renseignement pour le gouvernement américain en passant par la création d’équipes de développement internationales pour des organisations à but non lucratif. Il aime parler des choses qu’il a apprises en cours de route, et il aime aussi écouter et apprendre des autres.