Faut-il mettre les TODO dans le code source?

TL;PR : Utilisez des TODO temporaires lorsque vous travaillez sur une fonctionnalité, mais assurez-vous de les traiter avant de les fusionner. Ajoutez un lien vers un problème (issue) approprié dans votre TODO, ou supprimez-le du code. Vous devez avoir un backlog unique, partagé et visible des choses à faire. Ne laissez pas les TODO devenir invisibles.

Que pensez-vous des // commentaires TODO?

Le nombre de TODO présent dans une base de code est généralement une mesure informelle efficace (et bon marché) de sa maintenabilité. Il vous donne un aperçu des choses qui manquent ou qui devraient être modifiées, ce qui passe généralement inaperçu par d'autres mesures qui évaluent la qualité du code existant.

Moins il y a de TODO, plus la base de code est bonne. N'est-ce pas?

Et pourtant, laisser un TODO semble être une bonne idée lorsque vous le faites. En général, un TODO est rédigé pour informer les futurs développeurs de quelque chose d'important : quelque chose qui doit être ajouté, modifié ou ne doit pas être oublié. L'intention est souvent d'améliorer la qualité du code. Parfois, un commentaire TODO peut vous faire gagner beaucoup de temps!

Imaginez que vous travaillez sur une base de code contenant très peu de TODO. Vous comprenez tous les TODO qui s'y trouvent. L'estimation du coût des nouvelles fonctionnalités est plus simple : ces TODO vous fournissent tout le contexte dont vous avez besoin! Cela semble trop beau pour être vrai? Ce n'est peut-être pas si utopique si vous les utilisez comme un outil stratégique. Voyons un peu ce qui rend les TODO utiles.

Les inconvénients des TODO

Ceux qui ne sont pas exploitables.

Avez-vous déjà eu à travailler avec une base de code parsemée de TODO imprécis, datant de plusieurs années et rédigés par des développeurs qui ne font plus partie de la compagnie? Comme c'est frustrant de tomber sur un tel code :

const json = R.pickALL([
  "id",
  "type",
  "source",
  "details", // TODO: remove this
  'duration"
  ]);

Pourquoi devriez-vous les supprimer? Pourquoi n'ont-ils pas déjà été supprimés? Y a-t-il des effets secondaires dont vous devez tenir compte?

Les mystérieux TODO sèment le doute, ils vous ralentissent puisqu'ils vous contraignent à envisager des scénarios hypothétiques pour lesquels vous ne disposez pas forcément assez de contexte. Ainsi, plutôt que de vous aider ils vous déroutent.

En général, vous passez à autre chose et laissez ce TODO tel quel. Vous n'avez pas vraiment le temps d'y réfléchir, mais vous n'avez pas non plus l'impression de pouvoir le supprimer : peut-être était-il là pour une bonne raison? Encore une fois, vous n'avez pas le temps d'enquêter et de justifier pourquoi ce commentaire peut être supprimé.

Un backlog invisible et sans fin

Les grandes bases de code ont tendance à être encombrées de tels commentaires. Faites une recherche rapide dans votre base de code : combien de TODOs avez-vous? Dans le back-end sur lequel je travaille, nous en avons 141 pour le moment - ce qui est correct, j'ai vu pire.

Techniquement, chacun de ces// TODO est une chose que vous devez... faire. Il s'agit de 141 problèmes qui ont été détectés en dehors de notre système habituel de suivi de problèmes. Ils passent complètement inaperçus pour le gestionnaire de projet. Mais les développeurs les voient.

Chaque TODO ajoute un peu de pression aux développeurs qui travaillent sur la base de code. Une charge mentale que vous devez supporter au fur et à mesure que vous vous déplacez dans la base de code.

Enfin, ils vous détournent de votre objectif immédiat. Alors que vous essayez de vous concentrer sur la tâche à accomplir, vous rencontrez des pensées aléatoires qui peuvent y être reliées ou non. Et maintenant, vous devez examiner si cela a du sens avant de pouvoir revenir à votre tâche initiale.

Ce qui rend les TODO utiles

J'écris des commentaires TODO tous les jours. Cela m'aide à me concentrer sur la tâche à accomplir.

Cela peut sembler contradictoire. C'est parce que vous devez vous rappeler qu'il y a une distinction entre l'écriture et la lecture du code.

Les TODO peuvent être très problématiques pour les développeurs qui doivent les lire. En revanche, au moment de leur rédaction, ils sont très utiles :

1. Ils permettent de se sortir les idées de la tête. Avec les TODO, vous pouvez soulager vos pensées en retranscrivant peu à peu tout ce dont vous devez vous souvenir. Cela vous permet de mieux vous concentrer sur la tâche à accomplir.
2. Ils vous aident à vous familiariser avec la base de code. En exprimant vos idées sous forme de commentaires TODO, vous renforcez votre compréhension du fonctionnement du code et de ce qui doit être fait. Interagir avec le code en insérant des TODO est très efficace pour développer un modèle mental de code.
3. Ils apportent plus de contexte qu'une liste de TODO sur le côté. Vous pouvez écrire votre TODO à côté du code auquel il se réfère, là où cela a le plus de sens. Lorsque vous construisez votre modèle mental de code, il est très pratique de passer d'un TODO à un autre.

J'ai également fait la lecture de remarquables TODO au cours de ma carrière, ceux-ci m'ont permis de gagner du temps. En général, des commentaires bien rédigés peuvent vous aider à vous familiariser avec le contexte, cela permet d'éviter les erreurs lorsque vous touchez à un code qui vous est inconnu :

Ticket.create({
  age: passenger.age,
  // TODO: Seat Selection not supported yet for this scenario.
  passenger_selected_seat: null
});

Si vous rencontrez ce type de commentaire, vous disposerez de plus d'informations sur ce qui doit être fait. Vous vous rendrez peut-être compte que le problème n'est plus pertinent et que vous pouvez supprimer les TODO qui y sont associés. Ou bien vous remarquerez que vous ne pouvez pas passer outre ces TODO, puisque le problème auquel ils sont rattachés est encore pertinent.

De cette façon, vous n'oublierez aucun TODO dans la base de code, car vous pouvez simplement les rechercher à l'aide du numéro du problème. Une astuce simple pour résoudre le problème de la charge invisible!

Les bons TODOs procurent des informations utiles et apportent des précisions sur des sujets connexes.

J'écris des TODO toute la journée!

Ils m'aident à rester concentré sur ce que je fais. Chaque fois que je pense a quelque chose nécessaire pour avancer, je le dépose dans un TODO.

Je m'en débarrasse aussi petit à petit. Comme j'essaie de garder les PRs petits, je peux envoyer quelques commentaires TODO dans la branche principale. Lorsque je le fais, je m'assure de joindre le numéro du problème correspondant. De cette façon, je peux m'assurer que tout a été traité avant de fermer le ticket. Les nouveaux TODO ne restent pas longtemps dans la base de code. Ils sont un outil pratique pour m'aider à être productif et à ne pas oublier un cas limite.

Je ne suis pas un programmeur de génie, j'ai de bonnes astuces 🧙♂️

Que faire si vous avez déjà des centaines de TODO dans votre codebase?

Les TODOs commencent généralement à poser problème lorsqu'ils sont nombreux et lorsqu'ils sont répartis sur l'ensemble du codebase. Si la méthode heuristique qui précède vous permet de récupérer progressivement, vous recherchez peut-être une solution plus pragmatique pour tous les traiter, et ce dans un délai raisonnable.

Quel que soit l'outil que vous avez trouvé, rappelez-vous que l'objectif n'est pas de créer un énième outil de suivi des problèmes pour votre équipe. Un outil vraiment utile doit combler le vide entre votre base de code et le gestionnaire de problèmes que vous utilisez déjà.

Si vous utilisez GitHub (comme mon équipe), cet outil répondra à vos besoins :

Il analyse votre base de code, à la recherche de commentaires TODOs. Il vous donne des statistiques à ce sujet, ce qui peut être pratique si vous prévoyez de vous en débarrasser et que vous voulez mesurer les progrès réalisés.

Mais surtout, il met en évidence les TODO existants de façon à ce qu'ils soient visibles pour l'ensemble des personnes concernées, y compris le PM.

Je vous recommande de passer une heure par semaine avec le gestionnaire de projet jusqu'à ce que vous ayez épuisé le backlog des TODO existants. Pour chaque TODO, vous devez :

• Déterminer s'il est toujours pertinent, s'il est lié à un problème existant ou s'il doit être traité dans les 6 prochains mois.
• Si c'est le cas, créez un problème et mettez à jour la TODO pour y ajouter un lien vers le problème.
• Dans le cas contraire, supprimez la TODO du code.

La catégorisation de chaque TODO doit se faire rapidement. Si vous ne pouvez pas déterminer ce qu'il faut en faire (par exemple, vous ne pouvez pas déterminer son importance), créez un problème. Si cette question est toujours là 6 mois plus tard, c'est qu'elle n'est sûrement pas si importante que ça.

Il existe également une CLI si vous souhaitez l'intégrer à vos outils existants.

Cette simple habitude est un moyen réaliste de se libérer d'une base de code gonflée d'énigmes // TODO. De petites améliorations hebdomadaires peuvent sembler futiles au début, mais elles font des merveilles avec le temps, même sur les bases de code les plus gigantesques!

Merci à Nicolas Carlo pour cette collaboration. Vous pouvez lire la suite de ses articles sur sa page de blogue Understand Legacy Code ou encore jetez un coup d'oeil à son article sur comment se remettre rapidement au code suite à une réunion. N'oubliez pas de le suivre sur Twitter @nicoespeon!