La valeur de la Documentation de code

La documentation de code est la collection d’images et de descriptions écrites faciles à comprendre qui expliquent ce que fait une base de code et comment elle peut être utilisée.

Il peut s’agir de simples commentaires explicatifs au-dessus des fonctions et des blocs, ou d’un manuel du développeur à part entière, avec des tâches à faire et à ne pas faire de style normatif, des aperçus de chaque partie de l’application et des approches des types de tâches de codage les plus courants.

Il est souvent préférable de trouver un juste milieu entre ces deux extrêmes lorsque vous prenez la décision consciente de commenter votre code et de décrire les zones les plus difficiles d’une base de code en langage clair.

Pourquoi documenter votre code ?

Pourquoi avoir du mal à écrire sur votre code, au lieu de simplement écrire du code? Cela ne serait-il pas plus productif de toute façon?

Points de sauvegarde mentale

La documentation est comme un point de sauvegarde mentale pour les moments où vous obtenez enfin ce qui se passe à la fin de la journée et que vous ne voulez pas perdre de son élan. Un code bien documenté garantira que lorsque vous devrez vous replonger demain matin (ou dans plusieurs mois), vous n’aurez pas à prendre autant de temps pour vous mettre au courant.

Le code documenté est réutilisé

La différence entre une bibliothèque utilisée et une bibliothèque inutilisée se résume souvent à sa documentation.

Qui veut utiliser une bibliothèque open-source non documentée ou contribuer à un projet non documenté? Presque personne.

Dans la plupart des cas, vous préférez utiliser une bibliothèque moins puissante contenant des documents. Pourquoi? Parce que la documentation transmet d’autres informations sur une base de code. Les développeurs pensent que le projet vaut le temps et l’énergie d’écrire à ce sujet en langage clair afin que tous ceux qui pourraient être intéressés puissent rapidement commencer et apprendre comment cela fonctionne et pourquoi les décisions clés ont été prises.

Trouver un nouveau projet intéressant et bien documenté dans votre langue préférée peut être très excitant et amusant. Regardons l’alternative extrême: être obligé d’utiliser une bibliothèque de code non documentée et potentiellement contribuer à une base de code apparemment byzantine… cela semble assez douloureux, non?

Alors pourquoi n’avez-vous pas documenté votre propre code?

Documenter le code fait partie de l’écriture d’un bon code

Une pierre angulaire d’un bon code est la maintenabilité, obtenue grâce à une documentation compréhensible et lisible.

Il existe plusieurs façons de documenter le code:

• choisir de bons noms pour les variables et les fonctions
• laisser de brefs commentaires dans le code pour aider à donner du contexte aux futurs lecteurs
• ajouter des images illustratives telles que des diagrammes de relation de séquence et d’entité
• fournir des documents API, décrivant chaque classe, méthode, argument et valeur de retour
• en utilisant un langage typé statiquement, tel que TypeScript ( types comme documentation)

Comparez deux exemples

Supposons que vous obteniez des données d’une API backend et que vous les « ingressiez » – les convertissant en une forme plus utile pour un interface utilisateur frontale. Voici la première des deux solutions possibles.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

Le code ci-dessus a le potentiel d’être douloureux. Vous pouvez voir par le nom qu’il s’agit d’une sorte de convertisseur qui prend w comme paramètre.

Il semble qu’il renvoie un en-tête, peut-être des détails, et quelque chose appelé revs. D’où viennent les revs ? Bien sûr, il n’y a pas de détails sur les noms de variables entrants note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… ou y a-t-il? rr est-il l’abréviation de returned rev? Qui peut le dire.

Regardons le deuxième exemple.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

Wow, comme c’est différent! Cette fonction est dans un fichier util, donc le fichier principal est déjà moins encombré. Il est également écrit en TypeScript au lieu de JavaScript simple, nous avons donc l’avantage de définir des types pour nous guider.

Nous convertissons widgetRespDTO s en widget s. Bien que raccourci, nous avons une connaissance complète de ce qu’est wResp. Nous créons un widgetHeader, et un widgetDetail, c’est facile à voir. Nous comprenons également ce que sont oTS et cTS. Nous pouvons dire que WidgetRevisionsRespDTO s sont imbriqués à l’intérieur de WidgetRespDTO.

Quelqu’un a très gentiment renommé les variables entrantes afin que tous ceux qui voient ce code sachent ce qu’elles sont. Enfin, nous voyons qu’un Widget doit être composé de l’objet {widgetHeader, widgetDetail, widgetRevisions} retourné, car il doit correspondre au type de retour Widget spécifié en haut.

Quel code vous sentiriez-vous mieux à utiliser?

Qui en bénéficie?

Un code bien documenté profite à de nombreuses personnes:

Développeurs juniors

Parce qu’il est en langage simple et facile à comprendre, la documentation aide les développeurs juniors et les nouveaux membres de l’équipe à se sentir confiants en sautant dans une base de code. Cela évite la frustration et l’abandon précoce d’une tâche car elle se complique trop rapidement.

Il est également utile pour les développeurs juniors d’écrire leur propre documentation afin qu’ils puissent partager leur code avec d’autres et qu’ils puissent mieux comprendre leur code.

Développeurs seniors

En prenant le temps de documenter maintenant, les développeurs seniors passent moins de temps à expliquer leur code aux autres à l’avenir.

Ils peuvent également écrire du code plus complexe. La documentation en langage clair permet aux autres de l’utiliser comme une boîte noire, sans avoir à comprendre le fonctionnement interne.

Équipes & projets open source

Les changements de personnel peuvent entraîner un ralentissement considérable d’un projet. Un code à jour et bien documenté peut servir d’assurance contre de tels ralentissements et permettre aux membres restants de l’équipe de prendre du recul, de revoir le code à partir d’un niveau élevé et de décider de la meilleure ligne de conduite à suivre et, si nécessaire, d’intégrer de nouveaux employés.

Vous

Lorsque vous documentez du code, vous devez le résumer. Pour bien résumer, vous devez être capable de le comprendre, en tenant les différentes parties de votre tête en même temps. Écrire ou contribuer à la documentation est un raccourci pour vraiment comprendre une base de code, apporter d’énormes contributions et se sentir comme une grande partie d’une grande équipe.

Une bonne documentation peut ASSÉCHER notre expérience de codage

En tant que programmeur, vous avez probablement entendu parler du principe de ne pas vous répéter comme clé pour écrire du code propre et concis. Au lieu de répéter plusieurs fois le même bloc de code, écrivez une fonction qui peut être écrite une fois et utilisée dans toute votre application.

De la même manière, vous et votre équipe ne devriez pas rencontrer de problèmes similaires, puis réinventer la roue chaque fois que vous tentez de les résoudre. Par exemple, avez-vous déjà entendu l’un de vos collègues ou vous êtes-vous retrouvé à dire:

« Ah, j’ai résolu quelque chose de très similaire à cela, mais je ne me souviens jamais comment je le fais quand ça arrive… Je devrais probablement l’écrire quelque part, hein ? »

Vous vous retrouvez ensuite à scanner les mêmes threads de débordement de pile encore et encore.

Épargnez à vous-même et à vos collègues ce chagrin en suivant l’esprit du principe SEC et en rédigeant un document que vous pouvez employer à chaque fois que le problème se pose! Cela vous aidera, vous et les autres membres de votre équipe, à gagner du temps et à écrire plus efficacement du code plus simple, plus gérable et plus efficace.

Comment la documentation du code, ou son absence, vous a-t-elle affecté ?