Bien commenter son projet web

Actualité ekino -

…et concept de node-machine

Article paru le :
Citation Commentaire
Article paru le :

On parle de quoi ?

On parle des bons et des mauvais commentaires ou, plus simplement, de comment utiliser les commentaires à bon escient au sein de projets collaboratifs.
On parle aussi du concept node-machine ou d’un concept de librairie contenant, au sein même de son code et sans utilisation des commentaires, tous les éléments nécessaires à la création d’une documentation complète.

 

Des bons et des mauvais commentaires

Bon y’a le bon commentaire, il est là, il commente le code et c’est un bon commentaire … et y’a le mauvais commentaire, il est là, il commente le code mais bon c’est un mauvais commentaire quoi …

Plus concrètement il est difficile de qualifier un commentaires de bon ou de mauvais sans prendre en considération le contexte d’utilisation. C’est pourquoi la liste suivante – exemples de bons et de mauvais commentaires – n’est pas exhaustive et peut être sujet à discussion.

 

Les mauvais commentaires

 

Commentaires de “meublage”

Rôle escompté : Je ne sais pas quoi mettre dans cette portion de code mais je me dis que peut-être un jour ce sera utile.

Toutefois le rôle d’un commentaire n’est pas de remplacer une logique bancale ou un trou algorithmique. Souvent, il s’agit d’une partie à développer (TODO), à corriger (FIXME) ou qui ne devrait simplement pas exister.

 

Commentaires redondants

Rôle escompté : Permet d’expliquer dans un commentaire ce que représente telle variable ou méthode.

Toutefois il n’existe aucun intérêt à répéter ce qu’un code explicite dit déjà. La documentation type Javadoc reste un exception à discuter.

 

Commentaires de fermeture

Rôle escompté : Permet de mieux se repérer dans un code trop gros (ici, pour faciliter la lecture, l’exemple est léger).

Toutefois, c’est plutôt révélateur d’une mauvaise conception et pourrait être résolu avec un meilleur découpage en plusieurs fonctionnalités. Il est alors normalement suffisant de s’aider de l’indentation.

 

Commentaires de journal

Rôle escompté : Permet d’avoir un suivi des modifications réalisées dans le code (parfois le journal est intégré devant les déclarations de méthodes ou variables).

Toutefois, ce n’est pas le rôle des commentaires que de servir de système de versionning. Des outils dédiés comme SVN ou GIT remplissent très bien ce rôle. Si le but est de créer un changelog, il devrait figurer dans un fichier indépendant type CHANGELOG.md (et mieux être généré automatiquement).

 

Commentaires d’attribution

Rôle escompté : Identifier la personne responsable de la fonctionnalité ou de la création du fichier.

Toutefois, le commentaire n’a aucune pérennité sur un projet de plusieurs années (changement de l’équipe) et lorsque le but est en plus d’identifier un responsable, c’est symptomatique d’un manque de partage de connaissances au sein du projet.

 

Commentaires “artistique”

Rôle escompté : Une envie de se faire plaisir, de placer un genre d’easter egg.

Sans commentaire.

 

le code mort …

Rôle escompté : Garder visible l’existant pour facilement revenir en arrière.

Toutefois, le commentaire ne doit pas cacher les hésitations du développeur ou servir de système de versionning rapide. Il est souvent important de comprendre l’existant pour mieux transformer la fonctionnalité.

 

Les commentaire neutres

 

Commentaires légaux

Rôle escompté : Affichage de certaines raisons légales (licences notamment) obligatoires.

On préférera toutefois l’utilisation (si possible) d’un fichier externe présentant la licence.

 

Commentaires TODO/FIXME

Rôle escompté : Identifier des zones de code à terminer (développement en cours) ou à revoir ultérieurement (améliorations à faire).

On associera souvent un traceur des tags TODO et FIXME pour ne pas en oublier la résolution.

 

Les bons commentaires

 

Commentaires de clarification

Rôle escompté : Facilite la lecture et la compréhension du code dans le cas d’une syntaxe verbeuse.

La difficulté ici est que le commentaire sera jugé bon ou mauvais en fonction de s’il est suffisamment lisible naturellement pour les participants du projet (possédant parfois différents profils et niveaux). A vous de placer/connaître la position du curseur acceptable.

 

Commentaires d’avertissement/amplification

Rôle escompté : Met l’accent sur un comportement peu facile à comprendre.

Il s’agit ici de faire ressortir certains comportements liés au choix de l’algorithme, du modèle de données ou encore du langage qui peuvent être difficiles à cerner à la première lecture.

 

Et si on faisait autrement ?

Et si on pouvait se passer de commentaires ?
Et si le code parlait de lui-même ?
Et si on avant des exemples d’implémentation directement dans le code ?

Dans le monde Javascript, avec NodeJS, certains proposent une solution : La node machine !

 

Qu’est-ce qu’une node machine ?

The machine specification is an open standard for Javascript functions. Each machine has a single, clear purpose—whether it be sending an email, translating a text file, or fetching a web page. But whereas traditional functions are supposed to have only a single result, machines are aware of multiple possible outcomes. Machines are self-documenting, quick to implement, and simple to debug.” Mike McNeil

 

La spécification des machines est un standard ouvert pour les fonctions JavaScript. Chaque machine a un unique et clair but—que ce soit l’envoi de mail, la traduction d’un fichier texte ou le parcours d’un site web. Mais là où les fonctions traditionnelles sont sensées avoir un seul résultat, les machines ont la possibilité d’avoir plusieurs sorties. Les Machines sont auto-documentées, rapide à améliorer et simple à debogguer.” Mike McNeil

Une machine Node c’est donc :

  • Une librairie auto-documentée
  • Une librairie maîtrisant ses “sorties”
  • Une librairie au format universel

 

Une Node machine répond donc à ces besoins lorsque l’on souhaite utiliser une librairie :

  • Comment être sûr que la documentation est à jour ?
  • Comment être sûr de l’utilisation si je n’ai pas accès aux sources ?
  • Quels sont les paramètres de cette méthode ?
  • Quel est le genre de retours proposés par cette méthode ?

 

Solution Node-Machine

 

Classic usage paradigme

Voici un exemple classique d’utilisation d’une méthode fournie par une librairie externe :

En découle certaines questions :

  • La méthode myFunction existe-t-elle vraiment ?
  • Quels sont les paramètres qu’elle utilise ? Combien de paramètres utilise-t-elle ?
  • Quelle est la forme du retour positif/négatif ?

 

Les paramètres

Afin de répondre aux problèmes de l’utilisation des paramètres propres à une méthode, nous pouvons :

  • Les regrouper et en faire une structure exploitable par notre méthode
  • Ajouter du contenu – comme le caractère obligatoire du paramètre, une description voire un exemple de valeur…

Cette structure permet ensuite de générer directement une documentation complète sur la librairie, voire de répondre directement à un appel console (affichage des paramètres et d’un exemple complet d’appel).

 

Les callbacks

Pour répondre au besoin de connaître le comportement de retours des méthodes de la librairie, nous pouvons :

  • Les intégrer dans la librairie
  • Les décrire dans la libraire

Il sera alors plus facile de manipuler et d’anticiper les différents retours possibles prévus par la librairie sur une méthode donnée, voir d’avoir un exemple concret de données retournées.

 

La méthode

Finalement, sur le besoin de définition d’une méthode de la librairie, il suffit de la considérer comme :

  • Configurable via les inputs
  • Définie par ses exits

En pratique une méthode c’est donc :

 

La machine et les packs de machines

Il suffira ensuite d’englober nos différentes méthodes au sein d’une librairie transformée en Node machine, en y ajoutant du contenu propre à la machine, voire aux machines packs (regroupement de plusieurs machines).

Par l’exemple pour une machine :

Par l’exemple pour une machinepack :

 

Documentation générée

Le but est bien sûr de pouvoir non seulement utiliser facilement la librairie, mais aussi de générer une documentation exploitable par tout le monde. Par rapport à la structure même de la librairie, il est alors facile d’automatiser la génération de la documentation (en utilisant une machine Node par exemple…).

Ici, des exemples de la documentation générée pour le machine Facebook et sa méthode getAccessToken() sur le site de node machine.

Documentation Node Machine

 

Utilisation

Pour utiliser une machine dans l’environnement Node, rien de plus simple :

  • Utilisation directe :

 

  • Utilisation avec callbacks :

 

  • Utilisation avec configuration préalable des inputs :

 

Les spécifications

Toutes les spécifications, ainsi que la liste des librairies aujourd’hui disponible en tant que node machine, sont recensés sur le site node machine by Mike McNeil.

Qu'est-ce qu'une node machine

Spécifications d'une node machine

 

Conclusion

Il est aujourd’hui possible d’imaginer d’autres façons d’exploiter les commentaires ou de remplacer leurs utilisations par une description plus précise des comportements d’une libraire.

Il faudra bien entendu statuer sur la séparation entre le contenu et la documentation : le concept de Node machine a décidé de merger les deux efficacement pour faciliter la vie de tous les développeurs.

À vous d’imaginer d’autres possibilités et d’en partager les limites 😉

 

Références :

Laisser un commentaire