Dans le monde du développement logiciel, la revue de code est une étape incontournable pour assurer la qualité et la pérennité du code. Pourtant, cette pratique peut parfois s’avérer être un véritable casse-tête. Entre les commentaires peu clairs ou subjectifs, la communication peut rapidement dégénérer en discussions inutiles qui négligent souvent les aspects critiques.
C’est ici que les “Conventional Comments” peuvent intervenir dans les revues de code, transformant l'implicite par de l'explicite.
En standardisant la manière dont les feedbacks sont formulés dans les revues de code, les “Conventional Comments” clarifient les attentes et facilitent la compréhension mutuelle. Cette pratique permet notamment de réduire les malentendus et favorise des discussions plus efficaces.
Faire face à des malentendus
L'absence de contexte ou d'autres aides à la lecture peut rendre certains commentaires lors d'une revue de code brusques, ce qui risque de provoquer des incompréhensions et des conflits d'ego.
"Avec deux lignes d'écriture d'un homme, on peut faire le procès du plus innocent." Cardinal de Richelieu.
Un mauvais commentaire dans une code review prend souvent la forme suivante :
En y apportant de la forme, on peut apporter un contexte, une intention sans interprétations :
L'intention est définie, le ton de la phrase change.
Ou encore :
Le commentaire indique clairement au lecteur qu'un changement est suggéré, mais qu'il n'est pas nécessaire pour valider la revue.
La convention "Conventional Comments"
Les "conventional comments" sont un système de commentaire structuré pour les revues de code et d'autres formes de dialogue technique (commenter des RFC par exemple). Ils établissent un ensemble d'étiquettes prédéfinies, telles que : nitpick (critique mineure), issue (problème), suggestion, praise (éloge), question, reflexion, ou encore, non-blocking.
La structure comprend une étiquette (label), éventuellement agrémentée d'un ornement facultatif (decorations), suivie du sujet principal du commentaire, avec la possibilité d'engager une discussion plus approfondie.
Voici la liste des labels recommandés par la spécification :
- Praise: Les éloges (praises) mettent en valeur quelque chose de positif. Essayez de laisser au moins un de ces commentaires par revue. N'offrez pas de faux éloges (ce qui peut en fait être nuisible). Cherchez plutôt quelque chose à louer sincèrement.
- Nitpick: Les critiques minutieuses (niptick) sont des demandes triviales basées sur les préférences. Elles devraient être non bloquantes par nature.
- Suggestion: Les suggestions proposent des améliorations au sujet actuel. Il est important d'être explicite et clair sur ce qui est suggéré et pourquoi c'est une amélioration. Considérez l'utilisation de correctifs et des indications de blocage ou non-blocage pour communiquer davantage votre intention.
- Issue: Les problèmes (issues) mettent en évidence des problèmes spécifiques avec le sujet examiné. Ces problèmes peuvent être visibles par l'utilisateur ou en arrière-plan. Il est fortement recommandé d'associer ce commentaire à une suggestion. Si vous n'êtes pas sûr de l'existence d'un problème, envisagez de laisser une question.
- To do: Les tâches à faire (TO DO) sont de petits changements triviaux mais nécessaires. Distinguer les commentaires TO DO des problèmes ou des suggestions permet d'orienter l'attention du lecteur vers les commentaires nécessitant plus d'implication.
- Question : Les questions sont appropriées si vous avez une préoccupation potentielle mais n'êtes pas tout à fait sûr de sa pertinence. Demander à l'auteur des éclaircissements ou une enquête peut conduire à une résolution rapide.
- Thought: Les réflexions représentent une idée qui est apparue lors de l'examen. Ces commentaires ne bloquent pas par nature, mais ils sont extrêmement précieux et peuvent conduire à des initiatives plus ciblées et à des opportunités de mentorat.
- Chore: Les corvées (chores) sont des tâches simples qui doivent être accomplies avant que le sujet ne soit "officiellement" accepté. Habituellement, ces commentaires font référence à un processus courant. Essayez de laisser un lien vers la description du processus afin que le lecteur sache comment résoudre la corvée.
- Note: Les notes sont toujours non bloquantes et mettent simplement en évidence quelque chose que le lecteur devrait noter.
Ou encore de décorations :
- (non-blocking): Un commentaire avec cette décoration ne devrait pas empêcher l'acceptation du sujet en cours de révision. Cela est utile pour les organisations qui considèrent les commentaires bloquants par défaut.
- (blocking): Un commentaire avec cette décoration devrait empêcher le sujet en cours de révision d'être accepté, jusqu'à ce qu'il soit résolu. Cela est utile pour les organisations qui considèrent les commentaires non bloquants par défaut.
- (if-minor): Cette décoration accorde une certaine liberté à l'auteur, qui ne devrait résoudre le commentaire que si les modifications s'avèrent mineures ou triviales.
Les avantages de l'adoption des "Conventional Comments"
Expliciter : En standardisant les étiquettes et les formats, les "Conventional Comments" améliorent la clarté des commentaires, rendant le discours explicite éliminant les malentendus, assurant que tous les participants comprennent l'intention des commentaires.
Structurer : Les "Conventional Comments" simplifient la gestion et la structuration des commentaires, améliorant ainsi l'efficacité des revues de code et permettant aux développeurs de réagir plus rapidement aux retours. Par exemple, un commentaire de louange peut être directement associé à une partie spécifique du code, tandis qu'un commentaire de réflexion peut introduire des idées nécessitant une discussion plus approfondie.
Ouvrir le dialogue : Les "Conventional Comments" encouragent des échanges ouverts et constructifs. Grâce à la clarification du type de commentaire, les développeurs peuvent mieux saisir le sens et l'intention du feedback, ce qui accroît leur confiance dans la participation aux révisions. Par exemple, un commentaire de suggestion susceptible de susciter une discussion approfondie peut aboutir à des améliorations du code ou du design, renforçant ainsi le partage des connaissances au sein de l'équipe.
Conclusion
En adoptant les "Conventional Comments", les intentions des commentaires sont clarifiées, les commentaires sont contextualisés et les actions se retrouvent priorisées. Cette approche structurée rend les revues de code plus efficaces et productives, améliorant la clarté de la communication et encourageant des conversations ouvertes et constructives.
Lien vers la spécification : https://conventionalcomments.org/
