Utiliser une convention de nommage pour clarifier la collecte de données

Une célèbre citation attribuée à Martin Fowler rappelle que le nommage est une des tâches les plus difficiles :

There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors.

Je crois qu’elle s’applique particulièrement bien aux événements émis par une application pour être stockés puis analysés ultérieurement.

Pourquoi choisir avec soin les noms, dès le début ?

Photo by Scott Graham on Unsplash

Quand on commence à implémenter du suivi d’événements dans une application, on crée souvent rapidement les premiers événements, sans se poser trop de questions. D’une part, on souhaite accéder rapidement à la donnée, et d’autre part, s’il n’y a que 2 ou 3 événements suivis, ils sont en général très clairs !

On fait donc souvent l’impasse sur la définition d’une convention de nommage. Puis on finit par le payer le jour où l’on se retrouve avec des événements que l’on n’est plus capables de différencier sans lire le code pour comprendre leur déclenchement.

Et le coût du changement quand on a une grosse base d’événements suivis est assez lourd : ces événements sont générés par une application, puis stockés quelque part et utilisés par d’autres application. Il faut repenser le nommage de tous les événements, puis modifier le code qui les déclenche, migrer toutes les données existantes et réécrire les requêtes qui les utilisent.

C’est exactement la situation dans laquelle nous nous trouvons actuellement, donc prenons le temps de réfléchir un peu : qu’aurions-nous gagné à avoir une convention de nommage ?

Voilà les 3 principaux avantages qui remontent de nos discussions :

• produire des données claires, compréhensibles à la fois par les développeurs et par les équipes qui traitent les données (data analyst, équipes marketing, équipes produit…) ;
• écrire du code propre et sans surprise : les événements sont souvent des variables ou des paramètres de fonctions dans notre code, si leur nom est plus clair, le code est plus clair, on aime ;
• se poser moins de questions : si l’on souhaite mesurer un nouveau phénomène, on a déjà des règles simples pour nommer le nouvel événement à suivre.

Mais comment trouver des noms qui ont du sens ?

Avant de décider d’une convention de nommage, il faut prendre le temps de décrire ce qui constitue un événement.

Chacun se construit un modèle mental qui représente ce qu’est un événement. On n’y réfléchit en général pas trop, mais clarifier le modèle permet de s’accorder, en équipe, sur ce qu’on entend par événement, et ensuite de faire émerger une convention qui convienne à tous.

Chacun pourra adapter ce travail à son équipe et sa situation, mais voici ce qui constitue un événement selon nous :

• un acteur
• une action
• un objet
• un lieu
• un instant
• toutes sortes d’informations complémentaires, éphémères ou non

L’acteur

C’est l’entité qui réalise l’action représentée par l’événement.

Il peut s’agir d’un utilisateur (exemple : un visiteur s’inscrit), d’un programme (prélèvement automatique d’un abonnement mensuel), d’un phénomène naturel (le vent a fait pivoter la girouette), d’un animal (le chien mange) et bien d’autres, en fonction de l’univers de notre application.

En principe, il doit s’agir d’un nom commun.

L’action

C’est la nature de l’événement qui a eu lieu. On l’exprime par un verbe au passé ou participe passé. En général, le verbe représente une action ponctuelle et discrète (au sens mathématique).

Par exemple, “le visiteur s’est inscrit” : on peut considérer qu’il y a un avant et un après l’inscription, et qu’il y a un instant où l’inscription a lieu.

En revanche, “le client choisit un pack” manque de précision car le verbe ne représente pas une action ponctuelle. On ne sait pas trop si l’événement est déclenché quand le client a commencé à choisir ou à la fin : est-il déclenché quand il arrive sur la page ou quand il a sélectionné un pack ? L’événement n’est pas “discret”. Rien que “le client a choisi un pack” est plus précis, et donc plus compréhensible.

L’objet

L’entité à propos de laquelle l’action est réalisée. ça peut être par exemple un objet physique (le vent a activé la girouette), ou un élément visuel (le client a terminé son onboarding)

C’est souvent un nom commun. Il joue le rôle du complément d’objet (ou complément du verbe) dans la phrase en français. Un peu de grammaire ne fait pas de mal.

Le lieu

Où l’action a-t-elle eu lieu ? Si notre système s’étale sur plusieurs applications ou plusieurs espaces dans une seule application, il est intéressant de savoir sur laquelle l’événement est survenu.

C’est en général un nom.

L’instant

C’est la seconde ou la milliseconde à laquelle un événement survient. Elle est capitale pour extraire de l’information utile à partir de la liste des événements survenus.

Il est évidemment possible de ne stocker que la date ou l’heure, mais on perd alors de la précision, notamment si l’on veut étudier par la suite des événements qui se déclenchent séquentiellement, à quelques secondes d’intervalle.

Autres informations

On peut imaginer d’autres informations complémentaire, utiles pour caractériser l’événement, mais elles nous paraissent souvent optionnelles. Nous les renseignons souvent dans des propriétés optionnelles à attacher à un événement, plutôt que de les faire figurer dans son nom.

En bref

J’y ai fait allusion en parlant de l’objet, mais on remarque que les 6 éléments listés ci-dessus pour décrire un événement correspondent à des éléments de la grammaire française qu’on a tous étudiés.

• acteur = sujet
• action = verbe
• objet = complément du verbe
• lieu = complément circonstanciel de lieu
• instant = complément circonstanciel de temps
• informations complémentaires = autres compléments

Cela peut nous aider à définir la condition de nommage qu’on veut adopter : qu’est-ce qui est vraiment nécessaire, et qu’est-ce qui est du ressort de l’information complémentaire ?

On peut se dire par exemple que les compléments sont des informations complémentaires, et donc facultatives. 😮

La nouvelle syntaxe de la langue française : qu’est-ce qui nous intéresse pour nommer l’événement ?

Notre convention

Chez Captain Contrat, nous nous sommes mis d’accord sur la convention suivante :

Nomenclature : sujet_verbeaupassé_complémentdobjet

Le sujet peut prendre l’un des valeurs suivantes :

• “lawyer” si l’événement est toujours déclenché par une action d’un avocat
• “client” s’il est toujours déclenché par une action d’un client
• “admin” s’il est toujours déclenché par un équipier Captain
• “human” si ça peut être n’importe quel humain : avocat, client ou équipier
• “app” si c’est une action déclenchée automatiquement par notre application

Le verbe au passé peut être n’importe quel verbe, avec quelques “verbes réservés” :

• visited : s’il s’agit d’une visite de page
• clicked : s’il s’agit d’un clic sur un élément visuel sans conséquence importante sur les données, comme cliquer sur un tooltip d’aide

Le complément du verbe est un groupe nominal précis.

L’ensemble doit respecter la casse : snake_case.

Nos noms sont systématiquement définis en anglais, qui est la langue de travail de toutes nos applications.

Obsolescence

Au delà du problème initial, qui est de nommer correctement les événements quand on les implémente, nous nous posons aussi la question de leur obsolescence.

Ce problème n’est pas spécifique aux événements puisqu’il s’applique à l’ensemble du code, mais il se pose tout de même. Petit à petit, en fonction des évolutions du produit et du code, le nommage peut devenir obsolète.

Un événement trop vague devenu confus : question_asked

Quand cet événement a été implémenté, il était très clair qu’il correspondait à une question posée par un utilisateur qui possède un abonnement juridique chez nous et qui demande des renseignements à un juriste.

Les évolutions successives du produit ont ajouté de la confusion.

• Actuellement, une question peut aussi être posée par un juriste à un abonné, mais l’événement n’a pas changé. Il faut lire le code pour comprendre qu’il n’est déclenché que par les questions de l’abonné et pas par celles du juriste. Ou le contraire, je ne sais plus, il faudrait que je retourne lire le code 🤔
• Nous avons aussi dans l’application des questionnaires qui permettent aux utilisateurs (abonnés ou non) de générer des documents juridiques. On pourrait facilement croire que l’événement est déclenché lorsqu’un utilisateur doit répondre à une question, mais ce n’est pas le cas. Ce coup-ci, j’en suis sûr. Mais c’est parce que j’étais présent quand il a été développé et que j’ai accès au code.

Si cet événement n’est pas clair pour moi, qui l’ai implémenté et qui ai accès au code, j’imagine qu’il doit être frustrant pour les autres équipes.

Un événement trop précis : client_opened_payment_modal

Cet événement sert à mesurer le nombre de clients qui se retrouvent devant le formulaire de paiement. Cela nous permet ensuite de savoir quel pourcentage de clients laissent tomber au moment de payer.

Le jour où le paiement ne se fera plus dans une modale mais sur une page dédiée, le nom de l’événement deviendra obsolète.

Son nom est trop précis. Il est couplé à l’élément UX permettant de payer alors qu’ils n’est pas lié directement à cet élément dans l’intention. On aurait pu choisir client_displayed_payment_form qui est plus générique.

Comment lutter ?

Il est difficile de lutter contre l’obsolescence : un produit qui évolue crée nécessairement de la nouveauté et de l’obsolescence. En revanche, il me paraît important d’avoir quelques réflexes.

La première chose est de détecter l’obsolescence du nom de nos événements pour éviter les quiproquos. Pour cela, quelques pistes :

• quand je vais consulter le code pour savoir à quoi correspond un événement, c’est qu’il n’est pas clair, au moins pour moi
• quand les autres équipes nous demandent ce que représente un événement, c’est qu’il n’est pas clair pour eux
• si un événement n’est pas utilisé, peut-être que c’est parce que personne ne le comprend

Par la suite, pour limiter les conséquences des noms inappropriés, il est possible de mettre en place quelques actions :

1. documenter les événements pour que tout le monde puisse les comprendre
2. éviter de développer des fonctionnalités qui ont des noms proches (facile à dire)
3. être prêts à renommer un événement si c’est nécessaire. Si ça se produit souvent, semi-automatiser ?
4. assumer cette confusion et miser sur la connaissance accumulée par les équipiers pour s’y retrouver. Cette solution a l’avantage d’être peu coûteuse à court terme, mais bon…

Pour résumer

La difficulté de nommage des événements suivis vient de leur utilisation : ils sont émis par notre application, puis stockés ailleurs pour être utilisés par d’autres applications. Il est donc difficile de les modifier. Les nommer correctement est donc important.

Se mettre d’accord avec toutes les parties prenantes sur ce qui définit un événement ouvre la voie à une convention de nommage qui convienne à tous. Les noms des événements créés par la suite sont alors plus clairs et plus simples à utiliser par tous.

Enfin, pour revenir à la citation initiale, n’oublions pas non plus les bonnes pratiques de base pour le nommage :

• éviter l’ambiguïté : ne pas utiliser le même mot pour deux choses différentes
• éviter les abréviations (user_SU pour user_signed_up)
• éviter les mots réservés (“event” par exemple…)
• respecter les conventions de casse (snake_case, camelCase, kebab-case…)

Une fois que l’on parvient à suivre des événements dont le nom est à peu près clair, une nouvelle question se pose : comment clarifier les propriétés qui accompagnent chaque événement ?

Mais c’est une autre histoire…